# API keys

Create, inspect and revoke the secret credentials used to access an account.

API keys grant server-side access to every API resource owned by their account. Keep them out of browser code, mobile applications, source control and public documentation.

The `secret` is returned only when a key is created. It is `null` when the same key is retrieved or listed later. Store a newly created secret before discarding the response; FiscalRail cannot reveal it again.

An API key can create and revoke other keys, including itself. Use the dashboard to create the first key or recover access if all keys are revoked.

## The API Key object

### Properties

#### `id`

Type: `string`

Opaque identifier for an API key.

#### `object`

Type: `string`

String identifying this as an API Key object. Always `api_key`.

#### `live`

Type: `boolean`

True when the object belongs to the live environment; false for test data.

#### `account`

Type: `string`

Account this key authenticates as.

#### `name`

Type: `string`

Human-readable label describing where the key is used.

#### `suffix`

Type: `string`

Last four characters used to identify the key safely.

#### `secret`

Type: `string or null`

Full secret returned only during creation; null on every later response.

#### `created_at`

Type: `string`

When the API key was created.


### Example

```json
{
  "id": "acct_key_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "api_key",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "name": "Production server",
  "suffix": "4wW7",
  "secret": "ak_11111111111111111111111111111111111111111111",
  "created_at": "2026-08-10T09:30:00Z"
}
```

## Create an API key

`POST /v1/api-keys`

Creates an API key. The secret is returned by this operation only and cannot be retrieved later.

### Request body

#### `name`

Type: `string` — required

Human-readable label describing where the key will be used.


### Responses

- `201` — [An API Key object containing its newly issued secret.](#the-api-key-object) Formats: JSON.

### Example request

```bash
curl --request POST \
  'https://api.fiscalrail.com/v1/api-keys' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 201

```json
{
  "id": "acct_key_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "api_key",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "name": "Production server",
  "suffix": "4wW7",
  "secret": "ak_11111111111111111111111111111111111111111111",
  "created_at": "2026-08-10T09:30:00Z"
}
```

## Retrieve an API key

`GET /v1/api-keys/{id}`

Returns API key metadata. The secret is always null after creation.

### Path parameters

#### `id`

Type: `string` — required

The opaque ID of the API key.


### Responses

- `200` — [An API Key object.](#the-api-key-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/api-keys/acct_key_14Vxtqg6oXpAY5WdWoq4wW' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "id": "acct_key_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "api_key",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "name": "Production server",
  "suffix": "4wW7",
  "secret": "ak_11111111111111111111111111111111111111111111",
  "created_at": "2026-08-10T09:30:00Z"
}
```

## Revoke an API key

`DELETE /v1/api-keys/{id}`

Permanently revokes an API key. Revoking the key used for this request takes effect immediately after the response.

### Path parameters

#### `id`

Type: `string` — required

The opaque ID of the API key.


### Responses

- `204` — The API key was revoked. The response has no body.

### Example request

```bash
curl --request DELETE \
  'https://api.fiscalrail.com/v1/api-keys/acct_key_14Vxtqg6oXpAY5WdWoq4wW' \
  --header "Authorization: Bearer ak_test_..."
```

## List API keys

`GET /v1/api-keys`

Returns API keys in reverse chronological ID order. Stored keys never expose their secret.

### Query parameters

#### `limit`

Type: `integer`

Maximum number of resources to return. Defaults to `25`.

#### `starting_after`

Type: `string`

Return API keys older than this API key ID. Cannot be combined with `ending_before`.

#### `ending_before`

Type: `string`

Return API keys newer than this API key ID. Cannot be combined with `starting_after`.


### Responses

- `200` — [A list of API Key objects.](#the-api-key-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/api-keys?limit=25' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "object": "list",
  "has_more": null,
  "data": [
    {
      "id": "acct_key_14Vxtqg6oXpAY5WdWoq4wW",
      "object": "api_key",
      "live": true,
      "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
      "name": "Production server",
      "suffix": "4wW7",
      "secret": "ak_11111111111111111111111111111111111111111111",
      "created_at": "2026-08-10T09:30:00Z"
    }
  ]
}
```