Authentication

The Accounts API accepts one kind of caller: an account-org-level service-account credential, a credential made for one org. Every route acts on that org and no other.

Note: this differs from the GraphQL API, which uses personal access tokens (see Authentication & Security). A personal access token is not accepted here (401); a signed-in user's token is refused with 403.

1. Create a credential

In Admin Center, open the Credentials page and create a credential, choosing Manage for the one org it is for. Keep the client id and client secret safe: anyone who has them can act as the credential.

2. Request a token

Use the client_credentials grant at the token endpoint:

curl -s https://api.mapped.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"

The access_token is what you send (other fields of the response are omitted above). Tokens are short-lived: when a call answers 401 with the code token_expired, request a new one.

3. Send it as a bearer token

curl -s "https://api.mapped.com/v1/accounts/$ACCOUNT_ID/orgs/$ORG_ID/buildings" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Send the header exactly as Authorization: Bearer <token>: the scheme is Bearer with a capital B and one space. A lowercase bearer or a second space is not read, and the call answers 401 invalid_token. A request with no such header answers 401 missing_token; a browser session cookie is never accepted.

Finding your account id and org id

• The org id is in the token: it is the claim https://mapped.com/org of the access token. It is also in the Admin Center address of the org (/accounts/{accountId}/orgs/{orgId}).
• The account id is not in the token. It is the account that holds the org, and it is in the Admin Center address (/accounts/{accountId}/...).

What the credential may do

• Its own org only. orgId in the path must be the org the credential was made for, and accountId must be the account that holds that org. Anything else is 403 forbidden, and nothing is read or changed.
• Not account-level credentials. A credential made for a whole account is refused with 403 for now.
• Not user tokens. A signed-in user's token, an on-behalf-of token or any other kind of token is refused with 403.

Status	code	Meaning
401	missing_token	No Authorization: Bearer header
401	invalid_token	The token is not valid
401	token_expired	The token has expired; request a new one
403	forbidden	The credential is not allowed to use this route, org or account
503	upstream_unavailable	A check this API depends on is unavailable; retry

On each of the four routes, authentication is checked before anything else, so a call without a valid credential is a 401 whatever else it sent. Every error code is listed in Errors and limits.