API Keys
Using API Keys
API keys provide an alternative authentication method for integrating applications and services with Cryptofuse. Unlike OAuth 2.0 tokens, API keys are long-lived and meant for simpler integrations and development.
API Key Authentication
To authenticate requests using an API key, include the key in the X-API-Key header:
GET /payments/
X-API-Key: your_api_key_here
API Key vs. OAuth 2.0 Tokens
| Feature | API Keys | OAuth 2.0 Tokens |
|---|---|---|
| Lifetime | Long-lived (until revoked) | Short-lived (typically 10 hours) |
| Use Case | Simpler integrations, development | Secure server-to-server communications |
| Revocation | Can be revoked individually | Automatically expire after set time |
| Permissions | Fixed at creation time | Can be scoped with different permissions |
| Security | Must be stored securely as plaintext | More secure with automatic expiration |
API Key Security
Follow these security best practices when using API keys:
- Store API keys securely in environment variables or secure vaults
- Never include API keys in client-side code or publicly accessible repositories
- Use keys with the minimum permissions necessary for your use case
- Rotate keys periodically and whenever a security breach is suspected
- Implement proper monitoring and alerting for unusual API key usage
List API Keys
GET /api-keys
Retrieves a list of API keys associated with the current account. This endpoint requires OAuth 2.0 authentication.
Request Headers
| Header | Description |
|---|---|
| Authorization | Bearer token for authentication: Bearer <access_token> |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Maximum number of keys to return (default: 20, max: 100) |
| offset | integer | Number of keys to skip (for pagination) |
Example Request
GET /api-keys?limit=10&offset=0
Authorization: Bearer d1UUviKpHizUGsGZuboebXS6YgwcAl
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| keys | array | Array of API key objects |
| keys[].id | string | Unique identifier for the API key |
| keys[].name | string | User-defined name for the API key |
| keys[].created_at | string | ISO 8601 timestamp of when the key was created |
| keys[].last_used | string | ISO 8601 timestamp of when the key was last used (or null) |
| keys[].prefix | string | First few characters of the API key for identification |
| keys[].permissions | array | List of permissions assigned to this API key |
| total | integer | Total number of API keys matching the query |
Example Response
{
"keys": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Production API Key",
"created_at": "2025-03-15T12:00:00Z",
"last_used": "2025-04-16T14:30:00Z",
"prefix": "cryp_1a2b3c",
"permissions": ["read:payments", "write:payments", "read:withdrawals"]
},
{
"id": "c4b3a2d1-ab23-4cde-5f67-89ab0cdef123",
"name": "Development API Key",
"created_at": "2025-04-01T09:15:00Z",
"last_used": null,
"prefix": "cryp_7x8y9z",
"permissions": ["read:payments", "write:payments"]
}
],
"total": 2
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 401 | unauthorized | Authentication failed or token is missing |
| 403 | forbidden | Insufficient permissions to list API keys |
| 429 | rate_limit_exceeded | Too many requests in a short period |
Create API Key
POST /api-keys
Creates a new API key for the authenticated account. The full API key value is returned only once, immediately after creation.
Request Headers
| Header | Description |
|---|---|
| Authorization | Bearer token for authentication: Bearer <access_token> |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | A name to identify the purpose of this API key (max 64 chars) |
| permissions | array | Specific permissions to grant to this key. If omitted, default permissions are assigned |
| expiration | string | ISO 8601 timestamp when this key should expire. If omitted, the key never expires |
Example Request
POST /api-keys
Authorization: Bearer d1UUviKpHizUGsGZuboebXS6YgwcAl
Content-Type: application/json
{
"name": "Payment Processing Key",
"permissions": ["read:payments", "write:payments"],
"expiration": "2026-04-16T00:00:00Z"
}
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique identifier for the API key |
| name | string | The name you assigned to the API key |
| key | string | The full API key value (shown only once during creation) |
| prefix | string | First few characters of the API key for identification |
| created_at | string | ISO 8601 timestamp of when the key was created |
| expires_at | string | ISO 8601 timestamp of when the key will expire, or null if it never expires |
| permissions | array | List of permissions assigned to this API key |
Example Response
{
"id": "d78ef952-3c54-42ab-b79d-126835c18f32",
"name": "Payment Processing Key",
"key": "cryp_1a2b3c4d5e6f7g8h9i0jklmnopqrstuvwxyz",
"prefix": "cryp_1a2b3c",
"created_at": "2025-04-16T15:30:00Z",
"expires_at": "2026-04-16T00:00:00Z",
"permissions": ["read:payments", "write:payments"]
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Missing required fields or invalid data format |
| 401 | unauthorized | Authentication failed or token is missing |
| 403 | forbidden | Insufficient permissions to create API keys |
| 422 | invalid_permissions | One or more requested permissions are invalid or not available |
| 429 | rate_limit_exceeded | Too many requests in a short period |
Important Notes
- The full API key value (
key) is shown only once in the creation response. Store it securely as it cannot be retrieved later. - If you lose an API key, you must create a new one and delete the old one.
- API keys can have a subset of your account permissions, but never more permissions than your account.
- Consider setting an expiration date for API keys used in development or testing environments.
Revoke API Key
DELETE /api-keys/{key_id}
Revokes an API key, immediately invalidating it for all future requests. This action cannot be undone.
Request Headers
| Header | Description |
|---|---|
| Authorization | Bearer token for authentication: Bearer <access_token> |
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| key_id | string | The ID of the API key to revoke |
Example Request
DELETE /api-keys/d78ef952-3c54-42ab-b79d-126835c18f32
Authorization: Bearer d1UUviKpHizUGsGZuboebXS6YgwcAl
Response
A successful revocation returns a 204 No Content status code with no response body.
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 401 | unauthorized | Authentication failed or token is missing |
| 403 | forbidden | Insufficient permissions to revoke this API key |
| 404 | not_found | The specified API key does not exist or belongs to another account |
| 429 | rate_limit_exceeded | Too many requests in a short period |
Security Notes
- Revocation takes effect immediately and cannot be undone
- All requests using the revoked API key will fail with a 401 Unauthorized error
- Consider revoking API keys whenever:
- A key is no longer needed
- A key may have been compromised
- A developer leaves your team
- Your security policies require key rotation
- Maintain proper logging of API key revocations for security auditing