> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, access tokens, and permissions.

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

```text theme={null}
  [1] Create API key          Incard dashboard (shown once)
  [2] Exchange for token      POST /auth/v1/.../token  { api_key }
  [3] Call Developer API      Authorization: Bearer <access_token>
```

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

API keys are environment-specific. Sandbox keys start with `sk_sandbox_`; live keys start with `sk_live_`. Use the matching environment for both token exchange and API calls.

## Environments

| Environment | Base URL                         | Token endpoint                |
| ----------- | -------------------------------- | ----------------------------- |
| Sandbox     | `https://api-nonprod.incard.com` | `POST /auth/v1/sandbox/token` |
| Live        | `https://api.incard.com`         | `POST /auth/v1/token`         |

Use sandbox while integrating. Gateway paths are relative to the base URL (for example `GET /developer/companies`).

## Create an API key

Any active member of your company can create keys from the Incard dashboard. Choose sandbox or live when creating the key.

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.

Key limits per company: up to 5 active sandbox keys and 5 active live keys.

## 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:

```bash theme={null}
curl -sS -X POST "https://api-nonprod.incard.com/auth/v1/sandbox/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk_sandbox_YOUR_KEY"}'
```

Response:

```json theme={null}
{
  "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.

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

## Call the Developer API

Send the access token as a Bearer credential on every request:

```bash theme={null}
curl -sS "https://api-nonprod.incard.com/developer/companies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

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 and the company active at creation time. What that member can do on the Developer API follows the same role-based rules as in the Incard product.

Permissions are determined by the member's **company role**. An owner can access every endpoint their company is entitled to; an employee has the most restricted access. Create keys with a role 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.