# Apps and keys

An app has two environments (sandbox, production). API keys are created and revoked here, with the portal session.

## Create an app (with its sandbox and production environments)

`POST /apps`

Authentication: portal session

Body (JSON):

| Field | Type | | Description |
|---|---|---|---|
| `name` | string | required | Name shown in the console (2 to 80 characters). Unique per app within your account. |

```bash
curl -X POST "$INBOX_API/apps" \
  -H "Authorization: Bearer $INBOX_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My CRM"
  }'
```

Response 201:

```json
{
  "id": "8b2717b6-be9e-42c7-8889-6e3c6ea4cbe3",
  "name": "My CRM",
  "createdAt": "2026-11-12T08:33:45.324Z",
  "environments": [
    {
      "id": "7d3d2aa8-d312-48d7-894c-25b906dfa11a",
      "kind": "sandbox"
    },
    {
      "id": "badd0f25-05da-4716-8c28-f2fe1baba427",
      "kind": "production"
    }
  ]
}
```

## List the account's apps

`GET /apps`

Authentication: portal session

```bash
curl "$INBOX_API/apps" \
  -H "Authorization: Bearer $INBOX_SESSION"
```

Response 200:

```json
[
  {
    "id": "8b2717b6-be9e-42c7-8889-6e3c6ea4cbe3",
    "name": "My CRM",
    "createdAt": "2026-11-12T08:33:45.324Z",
    "environments": [
      {
        "id": "7d3d2aa8-d312-48d7-894c-25b906dfa11a",
        "kind": "sandbox"
      },
      {
        "id": "badd0f25-05da-4716-8c28-f2fe1baba427",
        "kind": "production"
      }
    ]
  }
]
```

## Generate an API key. The secret is shown only once.

`POST /apps/{appId}/keys`

Authentication: portal session

Parameters:

| Name | Location | Type | Description |
|---|---|---|---|
| `appId` | path | string |  |

Body (JSON):

| Field | Type | | Description |
|---|---|---|---|
| `name` | string | required | Name shown in the console (2 to 80 characters). Unique per app within your account. |
| `environment` | string | required | Key environment: `sandbox` for testing, `production` for sending to real recipients. |
| `scopes` | string[] | required | Scopes of the key. A key can only do what it has been granted. Values: messages:send, messages:read, templates:manage, webhooks:manage, connections:read, connections:manage, usage:read. |

```bash
curl -X POST "$INBOX_API/apps/APP_ID/keys" \
  -H "Authorization: Bearer $INBOX_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local dev",
    "environment": "sandbox",
    "scopes": [
      "messages:send",
      "messages:read",
      "connections:manage",
      "connections:read",
      "templates:manage",
      "webhooks:manage",
      "usage:read"
    ]
  }'
```

Response 201:

```json
{
  "id": "5ef37bc9-8aac-43ef-81b1-6bb3bdb66e78",
  "name": "Local dev",
  "prefix": "pk_test_bwcA3X-A",
  "environment": "sandbox",
  "scopes": [
    "messages:send",
    "messages:read",
    "connections:manage",
    "connections:read",
    "templates:manage",
    "webhooks:manage",
    "usage:read"
  ],
  "lastUsedAt": null,
  "revokedAt": null,
  "createdAt": "2026-11-12T08:33:45.382Z",
  "secret": "pk_test_26f602c48c47ef280792fd3a506473688df70b80118"
}
```

## List an app's keys (without the secret)

`GET /apps/{appId}/keys`

Authentication: portal session

Parameters:

| Name | Location | Type | Description |
|---|---|---|---|
| `appId` | path | string |  |

```bash
curl "$INBOX_API/apps/APP_ID/keys" \
  -H "Authorization: Bearer $INBOX_SESSION"
```

Response 200:

```json
[
  {
    "id": "5ef37bc9-8aac-43ef-81b1-6bb3bdb66e78",
    "name": "Local dev",
    "prefix": "pk_test_bwcA3X-A",
    "environment": "sandbox",
    "scopes": [
      "messages:send",
      "messages:read",
      "connections:manage",
      "connections:read",
      "templates:manage",
      "webhooks:manage",
      "usage:read"
    ],
    "lastUsedAt": null,
    "revokedAt": null,
    "createdAt": "2026-11-12T08:33:45.382Z"
  }
]
```

## Revoke an API key

`DELETE /apps/{appId}/keys/{keyId}`

Authentication: portal session

Parameters:

| Name | Location | Type | Description |
|---|---|---|---|
| `keyId` | path | string |  |

```bash
curl -X DELETE "$INBOX_API/apps/APP_ID/keys/KEY_ID" \
  -H "Authorization: Bearer $INBOX_SESSION"
```

Response 204:

```json
(no content)
```