Skip to main content

API Authentication

The GeniSpace API uses a hybrid Bearer authentication scheme. It accepts both JWT access tokens and API keys. All API requests must include valid authentication information in the request headers.

Obtaining an API Key​

Space-scoped API keys are managed in the Console:

  1. Open the Console and navigate to Settings → Integrations
  2. In the API key area, click "Create API Key"
  3. Store the generated key securely — the key is only displayed once at creation time

API keys are 40-character alphanumeric tokens (no sk- prefix), for example 8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t.

Usage​

Add the Authorization field to the HTTP headers of each API request:

Authorization: Bearer YOUR_API_KEY

The Bearer scheme is recommended. The API also accepts the ApiKey, API-Key, and Token prefixes for API keys:

Authorization: ApiKey YOUR_API_KEY
Authorization: API-Key YOUR_API_KEY
Authorization: Token YOUR_API_KEY

Request Example​

curl -X GET https://api.genispace.ai/api/agents \
  -H "Authorization: Bearer 8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t" \
  -H "Content-Type: application/json"

Validating an API Key​

To check whether a key is valid, call the validation endpoint (no authentication required):

curl -X POST https://api.genispace.ai/api/api-keys/validate \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t" }'

The response uses the standard envelope, with the result under data:

{
  "success": true,
  "message": "Operation successful",
  "data": {
    "valid": true
  }
}

An equivalent endpoint is available at POST /api/validate/api-key.

Security Recommendations​

  • Do not hardcode API keys in client-side code
  • Use environment variables to store keys
  • Rotate keys regularly
  • If a key is compromised, immediately revoke it (POST /api/api-keys/{id}/revoke) and create a new one

Permission Scope​

The permission scope of an API key depends on the creator's space role and subscription plan. The key can access resources belonging to its bound space.