# Authentication (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/authentication/
> Staging base URL: https://api-staging.coinbax.com

API key management and verification

## Create new API key

`POST /api/v1/auth/api-key`

- Auth: X-API-Key header
- Operation ID: `AuthController_createApiKey`

Generate a new API key for a platform. Requires an existing admin-scoped API key. The new API key is only shown once.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Platform name (3-100 characters) |
| `webhookUrl` | string | no | Webhook URL for receiving event notifications (must be HTTPS in production) |
| `settings` | object | no | Additional platform settings |
| `scopes` | array of enum ("read:transactions", "write:transactions", "cancel:transactions", "rescind:transactions", "read:customers", "write:customers", "read:templates", "write:templates", "read:disputes", "write:disputes", "submit:evidence", "read:webhooks", "write:webhooks", "read:compliance", "write:compliance", "read:platform", "write:platform", "manage:api-keys", "admin:platform") | no | API scopes to grant to this key. If not provided, defaults to read-only scopes. |

```json
{
  "name": "My Marketplace",
  "webhookUrl": "https://myapp.com/webhooks/coinbax",
  "settings": {
    "theme": "dark",
    "notifications": true
  },
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/api-key \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Marketplace",
  "webhookUrl": "https://myapp.com/webhooks/coinbax",
  "settings": {
    "theme": "dark",
    "notifications": true
  },
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}'
```

### Responses

**201** API key created successfully

```json
{
  "apiKey": "cbx_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "platformId": "string",
  "platformName": "string",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "createdAt": "2026-01-15T12:00:00.000Z",
  "warning": "Store this API key securely. It will not be shown again."
}
```

**400** Bad request

**401** Missing or invalid API key

**403** Caller lacks admin:platform scope

---

## Regenerate API key

`POST /api/v1/auth/api-key/regenerate`

- Auth: X-API-Key header
- Operation ID: `AuthController_regenerateApiKey`

Generate a new API key for an existing platform. The old key will be invalidated.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `platformId` | string | yes | Platform ID |

```json
{
  "platformId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/api-key/regenerate \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platformId": "123e4567-e89b-12d3-a456-426614174000"
}'
```

### Responses

**200** API key regenerated successfully

```json
{
  "apiKey": "cbx_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "platformId": "string",
  "platformName": "string",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "createdAt": "2026-01-15T12:00:00.000Z",
  "warning": "Store this API key securely. It will not be shown again."
}
```

**404** Platform not found

---

## Get current platform

`GET /api/v1/auth/platform/me`

- Auth: X-API-Key header
- Operation ID: `AuthController_getCurrentPlatform`

Get platform details for the authenticated API key

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-api-key` | header | string | yes |  |
| `X-API-Key` | header | string | yes | API key |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/auth/platform/me \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Current platform details

```json
{}
```

**401** Invalid or missing API key

---

## Get platform details

`GET /api/v1/auth/platform/{id}`

- Auth: X-API-Key header
- Operation ID: `AuthController_getPlatform`

Retrieve platform information by ID

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/auth/platform/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Platform found

```json
{}
```

**404** Platform not found

---

## Update platform

`PUT /api/v1/auth/platform/{id}`

- Auth: X-API-Key header
- Operation ID: `AuthController_updatePlatform`

Update platform settings

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Platform name |
| `webhookUrl` | string | no | Webhook URL |
| `isActive` | boolean | no | Platform active status |
| `settings` | object | no | Platform settings |
| `scopes` | array of enum ("read:transactions", "write:transactions", "cancel:transactions", "rescind:transactions", "read:customers", "write:customers", "read:templates", "write:templates", "read:disputes", "write:disputes", "submit:evidence", "read:webhooks", "write:webhooks", "read:compliance", "write:compliance", "read:platform", "write:platform", "manage:api-keys", "admin:platform") | no | API scopes granted to this platform |

```json
{
  "name": "string",
  "webhookUrl": "string",
  "isActive": true,
  "settings": {},
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}
```

### Example request

```bash
curl -X PUT https://api-staging.coinbax.com/api/v1/auth/platform/<id> \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "webhookUrl": "string",
  "isActive": true,
  "settings": {},
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ]
}'
```

### Responses

**200** Platform updated successfully

```json
{}
```

**404** Platform not found

---

## Deactivate platform

`DELETE /api/v1/auth/platform/{id}`

- Auth: X-API-Key header
- Operation ID: `AuthController_deactivatePlatform`

Deactivate a platform (soft delete)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Example request

```bash
curl -X DELETE https://api-staging.coinbax.com/api/v1/auth/platform/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**204** Platform deactivated successfully

**404** Platform not found

---

## List all platforms

`GET /api/v1/auth/platforms`

- Auth: X-API-Key header
- Operation ID: `AuthController_listPlatforms`

Get all platforms (admin only)

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/auth/platforms \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Platforms retrieved successfully

```json
[
  {}
]
```

---

## Verify API key

`POST /api/v1/auth/verify`

- Auth: X-API-Key header
- Operation ID: `AuthController_verifyApiKey`

Check if an API key is valid and active

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-api-key` | header | string | yes |  |
| `X-API-Key` | header | string | yes | API key to verify |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/auth/verify \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Verification result

```json
{
  "valid": true,
  "platformId": {},
  "platformName": {},
  "isActive": true
}
```