API Key Management
Create, list, rotate, and delete API keys for your account.
AuthenticationPermalink for this section
Key management endpoints support dashboard session auth and API-key auth. When you authenticate with an API key, that key must be associated with a SharpAPI user account; internal or service keys without user_id return 400 validation_error.
Security: API key management operations are sensitive. Only perform these from server-side code, never from a client-side application.
List API KeysPermalink for this section
Retrieve all API keys associated with your account.
GET /api/v1/account/keysExample RequestPermalink for this section
cURL
curl -X GET "https://api.sharpapi.io/api/v1/account/keys" \
-H "X-API-Key: YOUR_API_KEY"Response (200)Permalink for this section
{
"success": true,
"data": [
{
"id": "key_abc123def456",
"id_masked": "...23def456",
"name": "Production",
"tier": "pro",
"is_active": true,
"created_at": "2025-10-15T08:30:00Z",
"updated_at": "2026-02-08T14:22:10Z"
}
],
"meta": {
"count": 1,
"max_keys": 1
}
}meta.max_keys reflects your tier’s key limit: Free/Hobby/Pro = 1, Sharp = 2, Enterprise = 10.
Key Object FieldsPermalink for this section
| Field | Type | Description |
|---|---|---|
id | string | Unique key identifier. |
id_masked | string | Masked preview of the key id (... plus the last 8 characters). |
name | string | null | Human-readable key name. |
tier | string | Subscription tier associated with the key. |
is_active | boolean | Whether the key is currently active. |
created_at | string | ISO 8601 timestamp of key creation. |
updated_at | string | ISO 8601 timestamp of last key update. |
Create API KeyPermalink for this section
Generate a new API key for your account.
POST /api/v1/account/keysRequest BodyPermalink for this section
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Descriptive name for the key, max 100 characters. If omitted, the API assigns a default name. |
Example RequestPermalink for this section
cURL
curl -X POST "https://api.sharpapi.io/api/v1/account/keys" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Mobile App"}'Response (200)Permalink for this section
{
"success": true,
"data": {
"id": "key_new345mno678",
"key": "sk_live_new345mno678...",
"name": "Mobile App",
"tier": "pro"
},
"meta": {
"warning": "This is the only time the key value will be shown. Store it securely."
}
}Important: The full key value is only returned once at creation time. Store it securely immediately.
Delete API KeyPermalink for this section
Permanently revoke an API key.
DELETE /api/v1/account/keys/{keyId}Path ParametersPermalink for this section
| Parameter | Type | Description |
|---|---|---|
keyId | string | The key id to delete. |
Example RequestPermalink for this section
cURL
curl -X DELETE "https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012" \
-H "X-API-Key: YOUR_API_KEY"Response (200)Permalink for this section
{
"success": true,
"data": {
"deleted": true,
"key_id": "key_xyz789ghi012",
"message": "API key revoked successfully"
}
}This action is irreversible. Any application using the deleted key will immediately lose API access. You cannot delete the key you are currently authenticating with.
Error ResponsesPermalink for this section
404 Key Not Found
{
"error": {
"code": "not_found",
"message": "Key not found or not owned by you"
}
}400 Cannot Delete Current Key
{
"error": {
"code": "validation_error",
"message": "Cannot delete the API key you are currently using"
}
}Rotate API KeyPermalink for this section
Generate a new key value and replace an existing API key. By default, the old key is revoked immediately. You may request a grace period up to 72 hours.
POST /api/v1/account/keys/{keyId}/rotatePath ParametersPermalink for this section
| Parameter | Type | Description |
|---|---|---|
keyId | string | The key id to rotate. |
Request BodyPermalink for this section
| Field | Type | Required | Description |
|---|---|---|---|
gracePeriodHours | number | No | Keep the old key valid for this many hours, from 0 to 72. Defaults to 0. |
name | string | No | Name for the replacement key. Defaults to the old key’s name. |
Example RequestPermalink for this section
cURL
curl -X POST "https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"gracePeriodHours": 0}'Response (200)Permalink for this section
{
"success": true,
"data": {
"new_key": {
"id": "key_new789abc012",
"key": "sk_live_rotated789abc012...",
"name": "Production",
"tier": "pro"
},
"old_key": {
"id": "key_abc123def456",
"revoked": true,
"expires_at": null
}
},
"meta": {
"warning": "The new key value is only shown once. Store it securely.",
"message": "Key rotated. Old key has been revoked immediately."
}
}Immediate effect: Unless you request a grace period, the previous key value is revoked the instant rotation completes. Update your application configuration before the next API request. The new key value is only shown once.
Response HeadersPermalink for this section
Key management endpoints return standard rate-limit headers:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 294
X-RateLimit-Reset: 1782851940
X-Data-Delay: 0
X-Request-Id: 1782851943426721-511042Best PracticesPermalink for this section
- Use descriptive names - Name keys by their purpose, such as “Production Server” or “Staging”.
- Rotate regularly - Rotate keys periodically, such as every 90 days.
- Use separate keys per environment - Create distinct keys for production, staging, and development.
- Review inactive keys - Identify and clean up unused keys.
- Store keys in secrets management - Use environment variables or a secrets manager, never hardcode keys.
- Revoke compromised keys immediately - If a key is exposed, delete or rotate it right away.
Related EndpointsPermalink for this section
- Account Info - Account details and feature access
- Usage Stats - Request and usage statistics
- Authentication - How to use API keys for authentication