Skip to main content

Authentication

info

The OurPeople API is currently in a closed beta only.

Endpoint​

Every OurPeople account has its own endpoint URL for connecting to. For example, if you access your OurPeople console at:

https://example.ourpeople.com

your API endpoint URL will be:

https://example-api.ourpeople.co

Request​

The API uses token-based authentication.

For authentication, you will be supplied with a client id and secret. You can exchange these credentials for an access token and refresh token:

POST /v1/auth
Host: example-api.ourpeople.co
Content-Type: application/json

{
    "id": "your-client-id",
    "secret": "your-client-secret"
}

Will respond with something like:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "refresh_token": "c5a926a4a25b52548dd7f5aa61528fddc26d4d177a20c1558a4aefd29afbe044cfcea0770ca442dff0d011251df8b66f75ad446076f1494c02dfa755eca56729"
}

The JWT returned will contain a small amount of information about the user you have authenticated with, and include an expiry timestamp. You can find out more about JWTs at https://jwt.io/.

You should use the expiry timestamp to detect whether your access token is still valid. If not, you can use a refresh token to extend your session.

Refreshing​

Your auth token will only be valid for a short period of time. To extend your session, you can authenticate with your refresh token:

POST /v1/auth/refresh
Host: example-api.ourpeople.co
Content-Type: application/json

{
    "refresh_token": "c5a926a4a25b52548dd7f5aa61528fddc26d4d177a20c1558a4aefd29afbe044cfcea0770ca442dff0d011251df8b66f75ad446076f1494c02dfa755eca56729"
}

Will respond with something like:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "refresh_token": "c70078cd010f929fa832b8e2f2eda4fd3c52376eae27d19b071197ee630bb52c81f4e1bab0abdf8f1d9d165a6c797a511cb5d7af844dcb6cb145f9403e481091"
}

Authenticated requests​

Once you have an access token, you can use it to make authenticated requests to the API. You should include the token in the Authorization header of your request:

GET /v1/users
Host: example-api.ourpeople.co
Content-Type: application/json
Authorization: Bearer your-access-token