Authentication

The API uses an OAuth2-style resource owner password credentials flow. You exchange credentials for a short-lived access token and a refresh token, then send the access token as a bearer token on every subsequent request.

All three grant types below are submitted to the same endpoint:

POST /customer-api/v1/auth_token

You’ll need a client_id. In your seventhings instance, open Integrations → API to find it.

Username and password login

{
  "username": "your username",
  "password": "S3cR3tP4ßW0rD",
  "client_id": "hash456789012345678901234567890123456789",
  "grant_type": "password"
}

Refreshing a token

Access tokens expire after expires_in seconds (see the response below). Use the refresh_token to get a new access token without asking the user to log in again:

{
  "refresh_token": "2b57a8d37baf1ef3a436968da51149b2eddf7f0f",
  "client_id": "hash456789012345678901234567890123456789",
  "grant_type": "refresh_token"
}

Single sign-on (SSO)

If your instance is configured for SSO, exchange the authorization code returned by your identity provider:

{
  "provider_name": "...",
  "auth_code": "0.AU4AvAfVR74TOEesr5NM0atDfD8q_1GyO...",
  "client_id": "hash456789012345678901234567890123456789",
  "grant_type": "sso_auth_code"
}

Token response

All three grant types return the same shape:

{
  "access_token": "e68f38c2dca2add6c5528e16d7a2b453371e5870",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "2b57a8d37baf1ef3a436968da51149b2eddf7f0f",
  "user_id": 1
}

Using the access token

Send the access token on every request in the Authorization header:

Authorization: Bearer e68f38c2dca2add6c5528e16d7a2b453371e5870

Logging out

To revoke a token, send:

DELETE /customer-api/v1/auth_token

See the full auth_token reference for request/response schemas and error codes.