Authentication

important

The OurPeople REST 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

Authentication#

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 HTTP/1.1
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 HTTP/1.1
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"
}