Authentication

Every API operation under https://api.entendre.finance/v1 needs a credential. Send all requests over HTTPS.

Method	Use it when	Header
API key	Your own scripts and integrations use your data.	`X-API-Key: <api_key>`
OAuth 2.0	Your app accesses Entendre on behalf of other users.	`Authorization: Bearer <access_token>` or `X-API-Key: <access_token>`

API key
OAuth 2.0

Create a key in Organization → API in the Entendre dashboard. Choose All access or Read only. A read-only key cannot call write operations.

curl https://api.entendre.finance/v1/organization \
  -H "X-API-Key: $ENTENDRE_API_KEY"

Your organization is inferred from the key. You do not need to send an organization ID.

Firm API keys

Create a firm key in Firm Settings → API. To call a client’s data, send the client’s organization ID in the organization-id header. If you omit the header, the key uses its default client. A key without a default client can call firm operations only.

Status	`error.code`	Cause
`400`	`BAD_REQUEST`	The organization ID is not valid.
`403`	`FORBIDDEN`	The key is not scoped to that client.
`403`	`FORBIDDEN`	An OAuth access token was sent. Firm operations need a firm API key.
`404`	`CLIENT_NOT_FOUND`	No client of the firm matches the value.
`409`	`AMBIGUOUS_CLIENT`	A client name matches more than one client. Send an ID from `error.candidates`.

Use OAuth when your app accesses Entendre on behalf of another user. The user chooses an organization and grants access.Register your app. Send your app name and redirect URIs to your Entendre contact. Entendre allows your redirect host. Then register the client at POST https://api.entendre.finance/api/auth/oauth2/register (RFC 7591) to get a client_id. Register with "token_endpoint_auth_method": "none" for a public client that uses PKCE only. Otherwise the answer also has a client_secret: send it with HTTP Basic authentication to the token and revocation endpoints. Loopback redirect URIs such as http://localhost:3000/callback are allowed for development.Discover the endpoints. The server metadata is at https://api.entendre.finance/.well-known/oauth-authorization-server/api/auth (RFC 8414). The API’s protected resource metadata is at https://api.entendre.finance/.well-known/oauth-protected-resource (RFC 9728). The OAuth endpoints are not under /v1.

Scope	Access
`apis.read`	Read access.
`apis.all`	Read and write access.
`offline_access`	A refresh token together with the access token.

Authorization, refresh and revocation

Use the authorization code flow with PKCE S256. Send resource=https://api.entendre.finance in the authorization request and in the token request. Without it, the access token does not work on the API.

Redirect the user to https://api.entendre.finance/api/auth/oauth2/authorize with response_type=code, client_id, the registered redirect_uri, scope, resource, a random state, code_challenge and code_challenge_method=S256. Add offline_access to scope to get a refresh token.
Verify state when the user returns to your callback.
Exchange the code at POST https://api.entendre.finance/api/auth/oauth2/token with form fields grant_type=authorization_code, client_id, code, redirect_uri, resource and the original PKCE code_verifier.
Refresh at the same URL with grant_type=refresh_token, client_id, refresh_token and resource.
Disconnect at POST https://api.entendre.finance/api/auth/oauth2/revoke with form fields token (the refresh token) and client_id.

Access tokens expire after one hour. Refresh them before expiry. Refresh tokens expire after 90 days and rotate on use: store the replacement that each refresh returns. If you send a replaced refresh token again after 30 seconds, all refresh tokens of that user for your client stop working.An access token stays valid until it expires, also after you revoke the refresh token.

API key owner

A key has an owner when a user creates it. Operations that record who made a change, or that open a document, need an API key with an owner. Other keys receive HTTP 403.

Credential	Owner
All access key	The user who created it
Firm key	The user who created it
OAuth access token	The user who granted access
Read only key	None

Authentication errors

A missing, invalid or expired credential returns 401 with error.code set to UNAUTHORIZED:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API Key",
    "request_id": "req_76571ade851d4cc099f38a98611b2d88",
    "suggested_action": "Send an API key in X-API-Key, or an OAuth access token as Authorization: Bearer. Refresh an expired access token.",
    "documentation_url": "https://entendre.ai/docs/get-started/authentication"
  }
}

A 401 has a WWW-Authenticate: Bearer header. Its resource_metadata parameter gives the URL of the protected resource metadata. It also has error="invalid_token" when the credential that you sent is invalid or expired. A valid credential without the required access returns 403 with error.code set to FORBIDDEN.

Status	`error.message`	Fix
`401`	`API Key is required`	Send an API key in `X-API-Key`, or an access token in `Authorization`.
`401`	`Invalid or expired API Key`	Create a new key, or refresh the access token.
`401`	`Invalid or expired access token`	Refresh the access token and retry.
`401`	`Invalid authorization token`	Send an API key in `X-API-Key`. It does not work in `Authorization`.
`401`	`Missing authorization token`	On a firm operation, send the firm API key in `X-API-Key`.
`403`	`This API key is read-only and cannot perform write operations.`	Use an All access key or the `apis.all` scope.
`403`	`Missing required scope: <scope>`	Use a key or token that has this scope.
`403`	`API key has no associated user — mutations require an owner`	Use an API key with an owner.

Firm keys have more responses; see Firm API keys above. See Errors for other failures.

Keep credentials safe

Keep keys and tokens out of browser code and version control. Store them in a secrets manager or in environment variables. If a key is exposed, select Revoke key in the dashboard and create a new one.

Get Started

Guides

API key owner

Authentication errors

Keep credentials safe

​API key owner

​Authentication errors

​Keep credentials safe

API key owner

Authentication errors

Keep credentials safe