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/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, meta } = await response.json();
 
console.log(`${meta.count}/${meta.max_keys} key slots used`);
for (const key of data) {
  console.log(`${key.name ?? 'Unnamed'}: ${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'}
)
body = response.json()
 
print(f"{body['meta']['count']}/{body['meta']['max_keys']} key slots used")
for key in body['data']:
    print(f"{key['name'] or 'Unnamed'}: {key['id_masked']} ({key['is_active']})")

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 = custom.

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

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

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, meta } = await response.json();
console.log(`New key: ${data.key}`);
console.warn(meta.warning);

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'}
)
body = response.json()
print(f"New key: {body['data']['key']}")
print(body['meta']['warning'])

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"

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 { data } = await response.json();
console.log(`Deleted key: ${data.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'}
)
data = response.json()['data']
print(f"Deleted key: {data['key_id']}")

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}/rotate

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

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',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ gracePeriodHours: 0 })
  }
);
const { data, meta } = await response.json();
console.log(`New key value: ${data.new_key.key}`);
console.warn(meta.warning);

Python


import requests
 
response = requests.post(
    'https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate',
    json={'gracePeriodHours': 0},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
body = response.json()
print(f"New key: {body['data']['new_key']['key']}")
print(body['meta']['message'])

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-511042

Best 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.

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 (200)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

Request BodyPermalink 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