API Key Management

Create, list, rotate, and delete API keys for your account.

AuthenticationPermalink for this section

All key management endpoints require authentication via an existing API key. Available to all tiers.

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/keys

Example RequestPermalink for this section

cURL


curl -X GET "https://api.sharpapi.io/api/v1/account/keys" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
 
for (const key of data) {
  console.log(`${key.name}: ${key.id_masked} (${key.is_active})`);
}

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/account/keys',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
keys = response.json()['data']
 
for key in keys:
    print(f"{key['name']}: {key['id_masked']} ({key['is_active']})")

Response (200)Permalink for this section


{
  "data": [
    {
      "id": "key_abc123def456",
      "id_masked": "sharpapi_...f456",
      "name": "Production",
      "tier": "pro",
      "is_active": true,
      "created_at": "2025-10-15T08:30:00Z",
      "updated_at": "2026-02-08T14:22:10Z"
    },
    {
      "id": "key_xyz789ghi012",
      "id_masked": "sharpapi_...i012",
      "name": "Staging",
      "tier": "pro",
      "is_active": true,
      "created_at": "2026-01-05T12:00:00Z",
      "updated_at": "2026-02-07T09:15:30Z"
    }
  ],
  "meta": {
    "count": 2,
    "total": 2,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    },
    "updated_at": "2026-02-08T14:55:00Z"
  }
}

Key Object FieldsPermalink for this section

Field	Type	Description
`id`	string	Unique key identifier
`id_masked`	string	Masked preview of the key (first and last characters visible)
`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/keys

Request BodyPermalink for this section

Field	Type	Required	Description
`name`	string	Yes	A descriptive name for the key (e.g., “Production”, “Mobile App”)

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"}'

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'Mobile App' })
  }
);
const { data } = await response.json();
console.log(`New key: ${data.key}`);
// IMPORTANT: Store this key securely. It will not be shown again.

Python


import requests
 
response = requests.post(
    'https://api.sharpapi.io/api/v1/account/keys',
    json={'name': 'Mobile App'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
new_key = response.json()['data']
print(f"New key: {new_key['key']}")
# IMPORTANT: Store this key securely. It will not be shown again.

Response (201)Permalink for this section


{
  "data": {
    "id": "key_new345mno678",
    "key": "sharpapi_new345mno678pqr901stu234vwx567",
    "name": "Mobile App",
    "tier": "pro"
  }
}

Important: The full key value is only returned once at creation time. Store it securely immediately. Subsequent requests will only show the id_masked preview.

Delete API KeyPermalink for this section

Permanently revoke and delete an API key.


DELETE /api/v1/account/keys/{keyId}

Path ParametersPermalink for this section

Parameter	Type	Description
`keyId`	string	The `key_id` of the key 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"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012',
  {
    method: 'DELETE',
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);
const result = await response.json();
console.log(`Deleted key: ${result.key_id}`);

Python


import requests
 
response = requests.delete(
    'https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
result = response.json()
print(f"Deleted key: {result['key_id']}")

Response (200)Permalink for this section


{
  "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": "API key not found",
    "docs": "https://docs.sharpapi.io/en/api-reference/account-keys"
  }
}

400 Cannot Delete Current Key


{
  "error": {
    "code": "validation_error",
    "message": "Cannot delete the API key used to authenticate this request",
    "docs": "https://docs.sharpapi.io/en/api-reference/account-keys"
  }
}

Rotate API KeyPermalink for this section

Generate a new key value for an existing API key. The old key is immediately revoked and replaced with a new one.


POST /api/v1/account/keys/{keyId}/rotate

Path ParametersPermalink for this section

Parameter	Type	Description
`keyId`	string	The `key_id` of the key to rotate

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"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate',
  {
    method: 'POST',
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);
const { data } = await response.json();
console.log(`New key value: ${data.key}`);
// IMPORTANT: Update your application configuration with the new key immediately.

Python


import requests
 
response = requests.post(
    'https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
rotated = response.json()['data']
print(f"New key: {rotated['key']}")
# IMPORTANT: Update your application configuration with the new key immediately.

Response (200)Permalink for this section


{
  "data": {
    "key_id": "key_abc123def456",
    "name": "Production",
    "key": "sharpapi_rotated789abc012def345ghi678jkl",
    "key_preview": "sharpapi_...jkl",
    "status": "active",
    "rotated_at": "2026-02-08T15:10:00Z",
    "previous_key_revoked": true
  },
  "meta": {
    "updated_at": "2026-02-08T15:10:00Z"
  }
}

Immediate effect: 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.

Tip: If you are rotating the key you are currently authenticating with, the rotation will succeed, but you must use the new key for all subsequent requests.

Response HeadersPermalink for this section

All key management endpoints return standard rate limit headers:


X-RateLimit-Limit: 300
X-RateLimit-Remaining: 294
X-RateLimit-Reset: 1707401400
X-Data-Delay: 0
X-Request-Id: req_keys123xyz

Best PracticesPermalink for this section

Use descriptive names - Name keys by their purpose (e.g., “Production Server”, “Staging”, “Mobile App”) to easily identify them later
Rotate regularly - Rotate keys periodically (e.g., every 90 days) as a security best practice
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

Account Info - Account details and feature access
Usage Stats - Request and usage statistics
Authentication - How to use API keys for authentication

API Key Management

AuthenticationPermalink for this section

List API KeysPermalink for this section

Example RequestPermalink for this section

cURL

JavaScript

Python

Response (200)Permalink for this section

Key Object FieldsPermalink for this section

Create API KeyPermalink for this section

Request BodyPermalink for this section

Example RequestPermalink for this section

cURL

JavaScript

Python

Response (201)Permalink for this section

Delete API KeyPermalink for this section

Path ParametersPermalink for this section

Example RequestPermalink for this section

cURL

JavaScript

Python

Response (200)Permalink for this section

Error ResponsesPermalink for this section

Rotate API KeyPermalink for this section

Path ParametersPermalink for this section

Example RequestPermalink for this section

cURL

JavaScript

Python

Response (200)Permalink for this section

Response HeadersPermalink for this section

Best PracticesPermalink for this section

Related EndpointsPermalink for this section