Authentication - Incard Developer API

The Developer API uses a two-step credential model: a long-lived API key for token exchange, and a short-lived access token on every API request.

Overview

  [1] Create API key          Incard dashboard (shown once)
  [2] Exchange for token      POST /developer/auth  { api_key }
  [3] Call Developer API      Authorization: Bearer <access_token> + X-On-Behalf-Of

Credential	Lifetime	Used for
`api_key`	Until revoked	Token exchange only
`access_token`	~15 minutes	Developer API requests

API keys start with sk_. Use the key only on the token endpoint — send the returned access_token on Developer API requests. Gateway paths are relative to the base URL (for example GET /developer/company/invoices).

Create an API key

Any active member of your company can create keys from the Incard dashboard. The full secret is shown once at creation. Store it in a secrets manager or environment variable — you cannot retrieve it again. Listing keys in the dashboard shows only a prefix for identification. You can have up to 5 active keys per member. Revoke an unused key to free a slot.

Exchange for an access token

Exchange your API key for a short-lived access token before calling the Developer API. Send the key in the request body:

curl -sS -X POST "https://api.incard.com/developer/auth" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk_YOUR_KEY"}'

Response:

{
  "access_token": "<opaque-token>",
  "expires_at": "2026-05-28T14:43:58.000Z"
}

Cache the access_token and refresh it before expires_at. Do not send your API key on Developer API requests — only on the token endpoint.

Never log, commit, or expose API keys or access tokens. Use HTTPS for all requests.

Call the Developer API

Send the access token as a Bearer credential on every request. Protected endpoints also require X-On-Behalf-Of with the company UUID you are acting on behalf of:

curl -sS "https://api.incard.com/developer/company/invoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

When the token expires, exchange your API key again for a new one.

Permissions

An API key is tied to the member who created it. On each Developer API request, X-On-Behalf-Of selects which company the call applies to; the gateway checks that the member has access to that company and builds role-based headers for downstream services. Permissions follow the member’s company role for the company in X-On-Behalf-Of. An owner can access every endpoint their company is entitled to; an employee has the most restricted access. Create keys with a member account that has the permissions your integration needs. If the authenticated principal lacks permission for an endpoint, the API returns 403 Forbidden.

Revoke a key

Revoke keys from the Incard dashboard when they are no longer needed or may be compromised. Revoked keys cannot be used to obtain new access tokens. Outstanding access tokens remain valid until they expire.

​Overview

​Create an API key

​Exchange for an access token

​Call the Developer API

​Permissions

​Revoke a key

Overview

Create an API key

Exchange for an access token

Call the Developer API

Permissions

Revoke a key