Skip to main content
An API key suits a customer’s own systems. A vendor whose product is used by many andteam tenants, such as an ATS, uses an OAuth app instead. The vendor registers once, each tenant’s administrator installs it, and the vendor never holds a secret pasted from the tenant. The grant is client credentials: the app acts for itself in one tenant at a time.

​
How an app gets installed

  1. andteam registers the app. The vendor tells andteam its name and the field groups it asks for, each at Read or Write. andteam gives the vendor a client_id and a client_secret. The secret is shown once.
  2. A tenant administrator installs it under Settings, Integrations, Apps. The administrator chooses the companies and field groups, no more than the app asks for. Read where the app asks for Write is fine. Write where it asks only for Read is not.
  3. An install follows the same rules as a key. A group that needs approval waits for its approver, and an install with a Write switch names a requester. See Approvals and Making changes.

​
Get a token

The request is application/x-www-form-urlencoded. The answer carries access_token, token_type (Bearer), expires_in and scope. The token starts ato_ and is valid for one hour. It carries the install’s companies and field groups. Ask for a new one when it expires.

​
Call the API

Send the token as a key is sent:
Everything else is the same as for a key: field groups, rate limits, the write rules and problem types. An expired or unknown token is a 401 problem.

​
Errors

The token endpoint answers with RFC 6749 errors, not problem details: JSON with error and error_description.

​
Uninstall and rolling the secret

Uninstalling an app stops its tokens at once. No new token is issued for that tenant. When andteam rolls an app’s secret, the old secret keeps working for 24 hours, so the vendor can swap it without an outage. After that it answers invalid_client.