Authentication

The JOIN API authenticates every request with a company API token sent as a Bearer token.

curl https://api.join.com/v3/locations \
  -H "Authorization: Bearer $JOIN_API_TOKEN"

Company tokens

A token belongs to your company, not to the person who created it.

Property	Rule
Owner	The company. A token keeps working when the admin who created it leaves or is deleted.
Access	Full read and write access to the company's data through the API.
Format	New tokens start with `join_sk_`. Tokens migrated from v2 keys have no prefix.
Visibility	The full value is shown once, at creation. JOIN stores it in a form that cannot be read back.
Limit	10 active tokens per company. Revoked tokens do not count.
Expiry	None. A token works until it is revoked.
Editable	Only the name.

Use one token per integration. A separate token per system makes usage traceable in the token list and lets you revoke one integration without affecting the others.

Managing tokens

Tokens are managed in Settings → Developer → API tokens. The page is available to the System Admin role.

Action	Effect
Create	Name the token (unique, up to 100 characters) and copy the value from the confirmation dialog.
Rename	Changes the display name. The token value is unchanged.
Revoke	Invalidates the token immediately and permanently. Requests in flight and all later requests return `401 token_invalid`.

The token list shows each token's name, its masked form (join_sk_…IW7Y), who created it, when, and the date it was last used.

A lost token cannot be recovered. Create a new token, update the integration, then revoke the old one.

Rotating a token

Create a new token.
Deploy the integration with the new token.
Confirm in the token list that the new token shows a recent Last used date.
Revoke the old token.

Plan access

API access is part of the Advanced and Enterprise plans. While a company's plan does not include API access, its tokens return 401 token_invalid. Tokens are not revoked or deleted when the plan changes, and they work again as soon as the plan includes API access.

Authentication errors

Status	Code	Cause
`401`	`authentication_required`	The `Authorization` header is missing, or does not use the `Bearer` scheme.
`401`	`token_invalid`	The token is malformed, unknown, or revoked, or the company's plan does not include API access.

{
  "error": {
    "code": "token_invalid",
    "message": "The API token is invalid or has been revoked."
  }
}

Security recommendations

Keep tokens on the server. Never send a token to a browser or a mobile app.
Store tokens in a secret manager or environment variables, never in source control.
If a token may have been exposed, revoke it immediately. The join_sk_ prefix lets secret scanners recognise JOIN tokens in code and logs.