Authentication

The API uses the OAuth 2.0 Client Credentials Flow. Your integration sends its client ID and secret to the identity host and gets a bearer token back.

Pick your environment and the hosts on this page update to match.

Token Endpoint

POST https://identity-v2.metaforce.net/connect/token

This path is stable. We are moving Doc Gen onto Keycloak, which serves OAuth under different paths internally, but the identity host keeps accepting /connect/token and forwards it. You do not need to change your integration when that move happens, and you do not need to read the discovery document to find the endpoint.

Required Parameters

Send them as application/x-www-form-urlencoded.

Name	Type	Value
grant_type	string	client_credentials
client_id	string	Your client ID
client_secret	string	Your client secret
scope	string	api.external

Example Response

{
  "access_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use the token in the header of every call:

Authorization: Bearer <access_token>

Tokens last an hour. Cache the token and reuse it until it expires rather than asking for a new one on every call.

Your client must belong to a company

Statistics returns the data of one company. The company is taken from the token, so the client (or the user) that asks for the token must be linked to a company in Doc Gen. Use an API client registered for your company, see API Clients.

A token without a company is accepted as a valid sign-in, but Statistics returns no data for it: /analytics answers 403 and /analytics/prometheus answers 500.

Common failures

Status	Meaning	What to do
401	No token, an expired token, or a token that was issued for a different API	Request a new token and send it in the `Authorization` header
403	The token is valid but is not tied to a company	Use an API client registered for your company

The full list of responses for each call is on API Endpoints.