Home›REST API›Quickstart

Quickstart

Authenticate and make your first REST API call in about five minutes.

Authenticate and make your first REST API call in about five minutes. You will create an API key, exchange it for an access token, and call the API as a specific user.

Before you start

  • A Power User account, so you can create an API key in Control Panel.
  • Your intranet URL, for example https://{{intranet_url}}.
  • A terminal with cURL, or any HTTP client.

Note: The REST API acts as a specific user. Every call runs with that user's permissions, so results and allowed actions depend on who you authenticate as.

1. Find your tenant and API URL

Every request needs an X-Tenant header (your tenant GUID) and is sent to your intranet's API domain ({{api_domain}}). If you do not have these yet, follow How to get API information.

2. Create an API key and secret

Sign in as a Power User and open Control Panel > Security. Create an API key; a secret is generated once, at the same time. Copy the secret immediately — it is shown only once and cannot be retrieved later.

Warning: Anyone with the key and secret can call the API as any user. Keep them out of front-end code, and delete a key immediately if it is exposed.

3. Exchange the key and secret for an access token

The API key and secret are not sent on every request. Exchange them once for a short-lived access token using the authorization_code grant. Pass the ID of the user you want to act as in personid.

curl --request POST "https://{{api_domain}}/token?personid={{person_id}}" \
  --header "X-Tenant: {{tenant_id}}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code={{api_key}}__{{api_secret}}" \
  --data-urlencode "context=KeySecret"

The code value is your key and secret joined by a double underscore ({{api_key}}__{{api_secret}}). The response contains an access_token (use it on every request) and a refresh_token (use it to obtain a new access token when the current one expires).

{
  "access_token": "{{access_token}}",
  "refresh_token": "{{refresh_token}}",
  "token_type": "bearer",
  "expires_in": 3600
}

4. Make your first call

Call GET /api/people/me to fetch the profile of the authenticated user. Send the access token as a bearer token, along with the X-Tenant header.

curl "https://{{api_domain}}/api/people/me" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "X-Tenant: {{tenant_id}}"

A 200 OK response with the user's profile confirms your credentials, tenant and token are all working. If you get a 401, re-check the token and X-Tenant header; see Errors and status codes.

Next steps

Section: REST API