# OAuth 2.0 (Coinbax API)

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

## List OAuth clients

`GET /api/v1/oauth/clients`

- Auth: Bearer token
- Operation ID: `OAuthController_listClients`

List all OAuth clients for a platform

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `platformId` | query | string | yes |  |
| `workspaceId` | query | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/clients?platformId=<platformId>&workspaceId=<workspaceId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** List of OAuth clients

```json
[
  {
    "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
    "name": "My Integration App",
    "description": "Third-party integration for transaction processing",
    "scopes": [
      "read:transactions",
      "write:transactions"
    ],
    "isActive": true,
    "createdAt": "2026-02-24T12:00:00Z",
    "lastUsedAt": "2026-02-24T14:30:00Z"
  }
]
```

---

## Create OAuth client

`POST /api/v1/oauth/clients`

- Auth: Bearer token
- Operation ID: `OAuthController_createClient`

Register a new OAuth client for a platform. The client secret is only shown once.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `platformId` | string | yes | Platform ID the OAuth client belongs to |
| `workspaceId` | string | no | Optional workspace ID for workspace-scoped clients |
| `name` | string | yes | Name of the OAuth client |
| `description` | string | no | Description of the OAuth client |
| `scopes` | array of string | yes | List of scopes the client is authorized for |
| `grantTypes` | array of string | no | Grant types allowed for this client |
| `redirectUris` | array of string | no | Redirect URIs for authorization code flow (future use) |

```json
{
  "platformId": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440001",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "grantTypes": [
    "client_credentials"
  ],
  "redirectUris": [
    "https://example.com/callback"
  ]
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/clients \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "platformId": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440001",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "grantTypes": [
    "client_credentials"
  ],
  "redirectUris": [
    "https://example.com/callback"
  ]
}'
```

### Responses

**201** OAuth client created successfully

```json
{
  "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "clientSecret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "name": "My Integration App",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "createdAt": "2026-02-24T12:00:00Z",
  "warning": "Store the client secret securely. It will not be shown again."
}
```

**400** Invalid request or invalid scopes

---

## Get OAuth client details

`GET /api/v1/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `OAuthController_getClient`

### Parameters

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

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** OAuth client details

```json
{
  "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "isActive": true,
  "createdAt": "2026-02-24T12:00:00Z",
  "lastUsedAt": "2026-02-24T14:30:00Z"
}
```

**404** Client not found

---

## Delete OAuth client

`DELETE /api/v1/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `OAuthController_deleteClient`

Permanently delete an OAuth client and all its tokens

### Parameters

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

### Example request

```bash
curl -X DELETE https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** OAuth client deleted successfully

**404** Client not found

---

## Update OAuth client

`PATCH /api/v1/oauth/clients/{clientId}`

- Auth: Bearer token
- Operation ID: `OAuthController_updateClient`

Update OAuth client settings. Deactivating a client will revoke all its tokens.

### Parameters

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Name of the OAuth client |
| `description` | string | no | Description of the OAuth client |
| `scopes` | array of string | no | Updated list of scopes |
| `isActive` | boolean | no | Whether the client is active |

```json
{
  "name": "Updated Integration App",
  "description": "Updated description",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "isActive": true
}
```

### Example request

```bash
curl -X PATCH https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated Integration App",
  "description": "Updated description",
  "scopes": [
    "read:transactions",
    "write:transactions",
    "read:customers"
  ],
  "isActive": true
}'
```

### Responses

**200** OAuth client updated successfully

```json
{
  "clientId": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "name": "My Integration App",
  "description": "Third-party integration for transaction processing",
  "scopes": [
    "read:transactions",
    "write:transactions"
  ],
  "isActive": true,
  "createdAt": "2026-02-24T12:00:00Z",
  "lastUsedAt": "2026-02-24T14:30:00Z"
}
```

**404** Client not found

---

## Revoke all client tokens

`POST /api/v1/oauth/clients/{clientId}/revoke-all-tokens`

- Auth: Bearer token
- Operation ID: `OAuthController_revokeAllClientTokens`

Revoke all active access tokens for a client

### Parameters

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

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId>/revoke-all-tokens \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** All tokens revoked

**404** Client not found

---

## Get client token statistics

`GET /api/v1/oauth/clients/{clientId}/stats`

- Auth: Bearer token
- Operation ID: `OAuthController_getClientStats`

Get token usage statistics for a client

### Parameters

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

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/clients/<clientId>/stats \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Token statistics

**404** Client not found

---

## Revoke access token

`POST /api/v1/oauth/revoke`

- Auth: Bearer token
- Operation ID: `OAuthController_revoke`

Revoke an active access token by its JWT ID (jti)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token_jti` | string | yes | JWT ID (jti) of the token to revoke |

```json
{
  "token_jti": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/revoke \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "token_jti": "550e8400-e29b-41d4-a716-446655440000"
}'
```

### Responses

**200** Token revoked successfully

**404** Token not found

---

## List available OAuth scopes

`GET /api/v1/oauth/scopes`

- Auth: Public (no authentication)
- Operation ID: `OAuthController_listScopes`

Get the catalog of available OAuth scopes that can be assigned to clients

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/oauth/scopes
```

### Responses

**200** List of available scopes

```json
[
  {}
]
```

---

## OAuth 2.0 Token Endpoint

`POST /api/v1/oauth/token`

- Auth: Public (no authentication)
- Operation ID: `OAuthController_token`

Generate access token using Client Credentials flow (RFC 6749)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_type` | enum ("client_credentials") | yes | OAuth 2.0 grant type |
| `client_id` | string | yes | OAuth client ID |
| `client_secret` | string | yes | OAuth client secret |
| `scope` | string | no | Space-separated list of requested scopes (optional, defaults to all client scopes) |

```json
{
  "grant_type": "client_credentials",
  "client_id": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "client_secret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "scope": "read:transactions write:transactions"
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
  "client_secret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "scope": "read:transactions write:transactions"
}'
```

### Responses

**200** Access token generated successfully

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:transactions write:transactions"
}
```

**400** Invalid request or unsupported grant type

**401** Invalid client credentials