# Workspace OAuth (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-oauth/
> Staging base URL: https://core-staging.coinbax.com/api/v1

OAuth client management for workspaces

## List OAuth clients

`GET /workspaces/{id}/oauth/clients`

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

Get all OAuth clients for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

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

### Responses

**200** OAuth clients retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "clients": [
      {
        "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "clientId": "string",
        "clientSecret": "string",
        "name": "string",
        "description": "string",
        "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "scopes": [
          "transactions:read",
          "customers:write"
        ],
        "grantTypes": [
          "authorization_code"
        ],
        "redirectUris": [
          "https://example.com"
        ],
        "isActive": true,
        "createdAt": "2026-01-15T12:00:00.000Z",
        "updatedAt": "2026-01-15T12:00:00.000Z"
      }
    ]
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create OAuth client

`POST /workspaces/{id}/oauth/clients`

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

Create a new OAuth client for a workspace.

**Requires:** Workspace access

**Note:** The client secret is only returned once at creation time.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Display name for the OAuth client |
| `description` | string | no |  |
| `scopes` | array of string | yes | API scopes this client can access |
| `grantTypes` | array of enum ("authorization_code", "client_credentials", "refresh_token") | no |  |
| `redirectUris` | array of string (uri) | no |  |

```json
{
  "name": "My API Client",
  "description": "Client for mobile app",
  "scopes": [
    "transactions:read",
    "customers:write"
  ],
  "grantTypes": [
    "client_credentials"
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/clients \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My API Client",
  "description": "Client for mobile app",
  "scopes": [
    "transactions:read",
    "customers:write"
  ],
  "grantTypes": [
    "client_credentials"
  ]
}'
```

### Responses

**201** OAuth client created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "clientId": "string",
    "clientSecret": "string",
    "name": "string",
    "description": "string",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "scopes": [
      "transactions:read",
      "customers:write"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "redirectUris": [
      "https://example.com"
    ],
    "isActive": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get OAuth client

`GET /workspaces/{id}/oauth/clients/{clientId}`

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

Get details of a specific OAuth client.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID (e.g., coinbax_client_xxx) |

### Example request

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

### Responses

**200** OAuth client retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "clientId": "string",
    "clientSecret": "string",
    "name": "string",
    "description": "string",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "scopes": [
      "transactions:read",
      "customers:write"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "redirectUris": [
      "https://example.com"
    ],
    "isActive": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Delete OAuth client

`DELETE /workspaces/{id}/oauth/clients/{clientId}`

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

Permanently delete an OAuth client.

**Requires:** Workspace access

**Warning:** This action is irreversible and will revoke all associated tokens.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Example request

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

### Responses

**204** OAuth client deleted successfully (no content)

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Update OAuth client

`PATCH /workspaces/{id}/oauth/clients/{clientId}`

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

Update an OAuth client's settings.

**Requires:** Workspace access

**Note:** Deactivating a client will revoke all its tokens.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Display name for the OAuth client |
| `description` | string | no | Description of the client's purpose |
| `scopes` | array of string | no | API scopes this client can access |
| `isActive` | boolean | no | Whether the client is active (deactivating revokes all tokens) |

```json
{
  "name": "Updated Client Name",
  "description": "Updated description",
  "scopes": [
    "transactions:read",
    "customers:read"
  ],
  "isActive": true
}
```

### Example request

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

### Responses

**200** OAuth client updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "clientId": "string",
    "clientSecret": "string",
    "name": "string",
    "description": "string",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "scopes": [
      "transactions:read",
      "customers:write"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "redirectUris": [
      "https://example.com"
    ],
    "isActive": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Revoke OAuth client tokens

`POST /workspaces/{id}/oauth/clients/{clientId}/revoke-tokens`

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

Revoke all active access tokens for an OAuth client.

**Requires:** Workspace access

Use this when you need to immediately invalidate all tokens without
deleting the client itself.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Example request

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

### Responses

**200** Tokens revoked successfully

```json
{
  "success": true,
  "data": {
    "count": 5
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get OAuth client statistics

`GET /workspaces/{id}/oauth/clients/{clientId}/stats`

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

Get token usage statistics for an OAuth client.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `clientId` | path | string | yes | OAuth client ID |

### Example request

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

### Responses

**200** Statistics retrieved successfully

```json
{
  "success": true,
  "data": {
    "totalTokens": 150,
    "activeTokens": 12,
    "revokedTokens": 138
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## List available OAuth scopes

`GET /workspaces/{id}/oauth/scopes`

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

Get all available OAuth scopes that can be assigned to clients.

**Requires:** Workspace access

Scopes control what actions an OAuth client can perform.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/oauth/scopes \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Scopes retrieved successfully

```json
{
  "success": true,
  "data": {
    "scopes": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "scope": "transactions:read",
        "resource": "transactions",
        "action": "read",
        "description": "Read transaction data",
        "isActive": true
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "scope": "transactions:write",
        "resource": "transactions",
        "action": "write",
        "description": "Create and update transactions",
        "isActive": true
      }
    ]
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error