API-Schlüsselverwaltung

Erstellen, auflisten, rotieren und löschen Sie API-Schlüssel für Ihr Konto.

AuthentifizierungPermalink for this section

Endpoints zur Schlüsselverwaltung unterstützen die Dashboard-Session-Authentifizierung und die Authentifizierung per API-Schlüssel. Wenn Sie sich mit einem API-Schlüssel authentifizieren, muss dieser Schlüssel mit einem SharpAPI-Benutzerkonto verknüpft sein; interne oder Service-Schlüssel ohne user_id geben 400 validation_error zurück.

Sicherheit: Vorgänge zur API-Schlüsselverwaltung sind sensibel. Führen Sie diese ausschließlich von serverseitigem Code aus, niemals von einer clientseitigen Anwendung.

API-Schlüssel auflistenPermalink for this section

Rufen Sie alle mit Ihrem Konto verknüpften API-Schlüssel ab.


GET /api/v1/account/keys

BeispielanfragePermalink 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']})")

Antwort (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 gibt das Schlüssellimit Ihres Tarifs wieder: Free/Hobby/Pro = 1, Sharp = 2, Enterprise = individuell.

Felder des Key-ObjektsPermalink for this section

Feld	Typ	Beschreibung
`id`	string	Eindeutige Schlüsselkennung.
`id_masked`	string	Maskierte Vorschau der Schlüsselkennung (`...` plus die letzten 8 Zeichen).
`name`	string \| null	Menschenlesbarer Schlüsselname.
`tier`	string	Mit dem Schlüssel verknüpfter Abonnementtarif.
`is_active`	boolean	Ob der Schlüssel derzeit aktiv ist.
`created_at`	string	ISO 8601-Zeitstempel der Schlüsselerstellung.
`updated_at`	string	ISO 8601-Zeitstempel der letzten Schlüsselaktualisierung.

API-Schlüssel erstellenPermalink for this section

Generieren Sie einen neuen API-Schlüssel für Ihr Konto.


POST /api/v1/account/keys

AnfragetextPermalink for this section

Feld	Typ	Erforderlich	Beschreibung
`name`	string	Nein	Beschreibender Name für den Schlüssel, maximal 100 Zeichen. Wenn nicht angegeben, weist die API einen Standardnamen zu.

BeispielanfragePermalink 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'])

Antwort (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."
  }
}

Wichtig: Der vollständige key-Wert wird nur einmal zum Zeitpunkt der Erstellung zurückgegeben. Speichern Sie ihn umgehend sicher.

API-Schlüssel löschenPermalink for this section

Widerrufen Sie einen API-Schlüssel dauerhaft.


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

PfadparameterPermalink for this section

Parameter	Typ	Beschreibung
`keyId`	string	Die Kennung des zu löschenden Schlüssels.

BeispielanfragePermalink 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']}")

Antwort (200)Permalink for this section


{
  "success": true,
  "data": {
    "deleted": true,
    "key_id": "key_xyz789ghi012",
    "message": "API key revoked successfully"
  }
}

Diese Aktion ist nicht rückgängig zu machen. Jede Anwendung, die den gelöschten Schlüssel verwendet, verliert sofort den API-Zugriff. Sie können nicht den Schlüssel löschen, mit dem Sie sich gerade authentifizieren.

FehlerantwortenPermalink for this section

404 Schlüssel nicht gefunden


{
  "error": {
    "code": "not_found",
    "message": "Key not found or not owned by you"
  }
}

400 Aktueller Schlüssel kann nicht gelöscht werden


{
  "error": {
    "code": "validation_error",
    "message": "Cannot delete the API key you are currently using"
  }
}

API-Schlüssel rotierenPermalink for this section

Generieren Sie einen neuen Schlüsselwert und ersetzen Sie einen vorhandenen API-Schlüssel. Standardmäßig wird der alte Schlüssel sofort widerrufen. Sie können eine Übergangsfrist von bis zu 72 Stunden anfordern.


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

PfadparameterPermalink for this section

Parameter	Typ	Beschreibung
`keyId`	string	Die Kennung des zu rotierenden Schlüssels.

AnfragetextPermalink for this section

Feld	Typ	Erforderlich	Beschreibung
`gracePeriodHours`	number	Nein	Hält den alten Schlüssel für diese Anzahl von Stunden gültig, von `0` bis `72`. Standardwert ist `0`.
`name`	string	Nein	Name für den Ersatzschlüssel. Standardmäßig der Name des alten Schlüssels.

BeispielanfragePermalink 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'])

Antwort (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."
  }
}

Sofortige Wirkung: Sofern Sie keine Übergangsfrist anfordern, wird der vorherige Schlüsselwert in dem Moment widerrufen, in dem die Rotation abgeschlossen ist. Aktualisieren Sie Ihre Anwendungskonfiguration vor der nächsten API-Anfrage. Der neue key-Wert wird nur einmal angezeigt.

Antwort-HeaderPermalink for this section

Endpoints zur Schlüsselverwaltung geben standardmäßige Rate-Limit-Header zurück:


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

Verwenden Sie aussagekräftige Namen – Benennen Sie Schlüssel nach ihrem Zweck, etwa „Production Server“ oder „Staging“.
Regelmäßig rotieren – Rotieren Sie Schlüssel in regelmäßigen Abständen, etwa alle 90 Tage.
Verwenden Sie separate Schlüssel pro Umgebung – Erstellen Sie unterschiedliche Schlüssel für Produktion, Staging und Entwicklung.
Überprüfen Sie inaktive Schlüssel – Identifizieren und bereinigen Sie nicht verwendete Schlüssel.
Speichern Sie Schlüssel in einem Secrets-Manager – Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager, hardcoden Sie Schlüssel niemals.
Kompromittierte Schlüssel sofort widerrufen – Wenn ein Schlüssel offengelegt wird, löschen oder rotieren Sie ihn umgehend.

API-Schlüsselverwaltung

AuthentifizierungPermalink for this section

API-Schlüssel auflistenPermalink for this section

BeispielanfragePermalink for this section

cURL

JavaScript

Python

Antwort (200)Permalink for this section

Felder des Key-ObjektsPermalink for this section

API-Schlüssel erstellenPermalink for this section

AnfragetextPermalink for this section

BeispielanfragePermalink for this section

cURL

JavaScript

Python

Antwort (200)Permalink for this section

API-Schlüssel löschenPermalink for this section

PfadparameterPermalink for this section

BeispielanfragePermalink for this section

cURL

JavaScript

Python

Antwort (200)Permalink for this section

FehlerantwortenPermalink for this section

API-Schlüssel rotierenPermalink for this section

PfadparameterPermalink for this section

AnfragetextPermalink for this section

BeispielanfragePermalink for this section

cURL

JavaScript

Python

Antwort (200)Permalink for this section

Antwort-HeaderPermalink for this section

Best PracticesPermalink for this section

Verwandte EndpointsPermalink for this section