API Key Management

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

Authentication

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 Keys

Retrieve all API keys associated with your account.


GET /api/v1/account/keys

Example Request

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)


{
  "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 Fields

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 Key

Generate a new API key for your account.


POST /api/v1/account/keys

Request Body

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

Example Request

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)


{
  "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 Key

Permanently revoke and delete an API key.


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

Path Parameters

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

Example Request

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)


{
  "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 Responses

404 Key Not Found


{
  "error": {
    "code": "not_found",
    "message": "API key not found",
    "docs": "https://sharpapi.io/docs/api-reference/account-keys"
  }
}

400 Cannot Delete Current Key


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

Rotate API Key

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 Parameters

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

Example Request

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)


{
  "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 Headers

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 Practices

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

Authentication

List API Keys

Example Request

cURL

JavaScript

Python

Response (200)

Key Object Fields

Create API Key

Request Body

Example Request

cURL

JavaScript

Python

Response (201)

Delete API Key

Path Parameters

Example Request

cURL

JavaScript

Python

Response (200)

Error Responses

Rotate API Key

Path Parameters

Example Request

cURL

JavaScript

Python

Response (200)

Response Headers

Best Practices

Related Endpoints