Untether LabsDevelopers

Accessing the API

Learn how to access the Untether Labs API

The Untether Labs API uses OAuth 2.0 client_credentials grant for machine to machine authentication. You may read more information on this flow here.

Obtaining Credentials#

API access must be enabled for your company. If it isn't yet, please reach out.

Once it is, an admin can create API clients in Company settings > API clients:

  1. Click New API client.
  2. Name it after the integration that will use it, then click Create.
  3. Copy the Client ID and Client secret. The secret is shown only once; if you lose it, rotate it to get a new one.
  • Client ID: A public identifier for your application.
  • Client Secret: A secret known only to your application and the authorization server.

Sandboxes have their own API clients. Create them on the same page while signed in to the sandbox.

Access Token Exchange#

The Client ID and Client Secret do not provide access to the API by themselves, you must exchange them for a short-lived access token. This is accomplished by sending them to the /oauth2/token endpoint:

Token Request
curl -X POST --location "https://auth.untetherlabs.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'
Token Response
{
    "access_token": "{ACCESS_TOKEN}",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": 1793190145
}

expires_in is the token's lifetime in seconds, and expires_at is when it expires as a Unix timestamp in seconds.

If you have a legacy API client

Clients that were created for you by Untether support, before API clients could be managed in company settings, exchange their credentials at a different URL and receive a slightly different response:

Legacy Token Request
curl -X POST --location "https://app.untetherlabs.com/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'
Legacy Token Response
{
    "access_token": "{ACCESS_TOKEN}",
    "token_type": "Bearer",
    "expires_at": "{ISO TIMESTAMP}"
}

Legacy clients keep working, and there is no end-of-life date for them yet. When there is one, we will announce it well in advance and send reminders before it. To migrate:

  1. Create a new client in Company settings > API clients.
  2. Switch your token URL from https://app.untetherlabs.com/api/oauth/token to https://auth.untetherlabs.com/oauth2/token.

Your First Request#

With an access token, you are now free to make requests to the API any time before expires_at.

For example, we can fetch our own user information:

First API Request
curl -X GET --location "https://app.untetherlabs.com/api/v1/users/{CLIENT_ID}" \
    -H "Authorization: Bearer {ACCESS_TOKEN}"
Get User Response
{
    "id": "{CLIENT_ID}",
    "type": "bot",
    "name": "My API Client",
    "email": "api@untetherlabs.com",
    "status": "active"
}

For more information about this endpoint, see GET /v1/users/{userId} in the API reference.

Rotating the Client Secret#

To replace a client's secret, for example if it may have leaked or you have lost it, open Company settings > API clients, choose Rotate secret from the client's menu and copy the new secret. Like a new client's, it is shown only once.

The old secret stops working immediately, so anything still using it cannot get new access tokens until it is updated. Access tokens it already obtained keep working until they expire, within the hour.