Skip to main content

API Keys Management

Complete guide to creating and managing your API keys.

Overview​

API Keys are the primary way to authenticate with YODI APIs. Each key is:

  • Unique - Only you have access to your keys
  • Secure - Never shared or logged
  • Revocable - Can be deleted at any time
  • Rotatable - Can be replaced without losing functionality
  • Trackable - You can see which key made which request

Key management routes authenticate with a JWT access token, not with the API key being managed. Ordinary reads return safe metadata only: the stored key verifier is never returned. A newly created or rotated plaintext key is shown only in that operation's response.

Creating an API Key​

Endpoint: POST /api-key/create

Via Dashboard​

  1. Log in to https://console.yodi.tg
  2. Go to Settings → API Keys
  3. Click Generate New Key
  4. Give it a descriptive name (e.g., "Production Server", "Mobile App")
  5. Copy the key immediately (you won't see it again!)

Via API​

curl -X POST "https://api.yodi.tg/v1/api-key/create" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response:

{
  "message": "SUCCESS",
  "error": false,
  "data": {
    "id": 101,
    "key": "<plaintext-secret-returned-once>",
    "name": "Key-<timestamp>",
    "isActive": true,
    "maxRequests": null,
    "rateLimit": null,
    "expiresAt": null,
    "usageCount": 0,
    "lastUsed": "<timestamp>",
    "userId": 42,
    "createdAt": "<timestamp>",
    "updatedAt": "<timestamp>"
  },
  "meta": { "request_id": "<request-id>", "served_at": "<timestamp>" },
  "status": 201
}

Viewing Your Keys​

Endpoint: GET /api-key/user/{userId}

List keys for the authenticated account. Non-staff callers cannot use the path to select another account; staff access is controlled by the backend role policy. Foreign key IDs are returned as not found.

curl -X GET "https://api.yodi.tg/v1/api-key/user/42" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response:

{
  "message": "SUCCESS",
  "error": false,
  "data": [
    {
      "id": 101,
      "name": "Production",
      "isActive": true,
      "maxRequests": null,
      "rateLimit": null,
      "expiresAt": null,
      "usageCount": 0,
      "lastUsed": "<timestamp>",
      "userId": 42,
      "createdAt": "<timestamp>",
      "updatedAt": "<timestamp>"
    },
    {
      "id": 102,
      "name": "Staging",
      "isActive": false,
      "maxRequests": 1000,
      "rateLimit": 20,
      "expiresAt": null,
      "usageCount": 12,
      "lastUsed": "<timestamp>",
      "userId": 42,
      "createdAt": "<timestamp>",
      "updatedAt": "<timestamp>"
    }
  ],
  "meta": { "request_id": "<request-id>", "served_at": "<timestamp>" },
  "status": 200
}

Get Key Details​

The response contains safe metadata (id, name, active state, limits, expiry, usage timestamps, and owner ID). It never contains the stored key verifier or the plaintext secret.

Endpoint: GET /api-key/{id} (the generated key ID is a positive integer)

curl -X GET "https://api.yodi.tg/v1/api-key/101" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Update Key Settings​

Endpoint: PATCH /api-key/{id}

Only maxRequests, rateLimit, and expiresAt are accepted. Unknown fields, empty payloads, and attempts to set the key or active state are rejected. Use null for a nullable setting to remove its override. Success uses message: API_KEY_UPDATED and returns the key ID in data.

curl -X PATCH "https://api.yodi.tg/v1/api-key/101" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maxRequests": 200,
    "rateLimit": 20,
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

At least one supported field is required. Use the rotate endpoint to replace a key; the PATCH route cannot set a key value or reactivate a revoked key.

Rotate API Key​

Endpoint: POST /api-key/{id}/rotate

Generate a new key while keeping the same name and settings. The old key becomes invalid.

curl -X POST "https://api.yodi.tg/v1/api-key/101/rotate" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response:

{
  "message": "KEY_ROTATED_SUCCESS",
  "error": false,
  "data": {
    "id": 101,
    "key": "<new-plaintext-secret-returned-once>",
    "name": "Production",
    "isActive": true,
    "maxRequests": null,
    "rateLimit": null,
    "expiresAt": null,
    "usageCount": 12,
    "lastUsed": "<timestamp>",
    "userId": 42,
    "createdAt": "<timestamp>",
    "updatedAt": "<timestamp>"
  },
  "meta": { "request_id": "<request-id>", "served_at": "<timestamp>" },
  "status": 200
}
Important

The old key will be immediately revoked. Update all services using the old key within 5 minutes.

Revoke API Key​

Endpoint: POST /api-key/{id}/revoke

Permanently disable an API key. This action cannot be undone.

curl -X POST "https://api.yodi.tg/v1/api-key/101/revoke" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response:

{
  "message": "KEY_REVOKED_SUCCESS",
  "error": false,
  "data": {
    "id": 101,
    "name": "Production",
    "isActive": false,
    "maxRequests": null,
    "rateLimit": null,
    "expiresAt": null,
    "usageCount": 12,
    "lastUsed": "<timestamp>",
    "userId": 42,
    "createdAt": "<timestamp>",
    "updatedAt": "<timestamp>"
  },
  "meta": { "request_id": "<request-id>", "served_at": "<timestamp>" },
  "status": 200
}
danger

Revoking a key will immediately stop all requests using that key.

Delete API Key​

Endpoint: DELETE /api-key/{id}

curl -X DELETE "https://api.yodi.tg/v1/api-key/101" \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response:

{
  "message": "API_KEY_DELETED",
  "error": false,
  "data": { "id": 101 },
  "meta": { "request_id": "<request-id>", "served_at": "<timestamp>" },
  "status": 200
}

Security Best Practices​

Key Management​

Create separate keys for:

  • Production environment
  • Development environment
  • Testing/Staging
  • Different services/applications

Key Rotation​

Rotate keys periodically (recommended: every 90 days) Rotate immediately if key is compromised

Storage​

Store keys in environment variables:

# .env
YODI_API_KEY=sk_live_your_key_here

Use secret management tools:

  • AWS Secrets Manager
  • Azure Key Vault
  • HashiCorp Vault
  • Docker Secrets

Monitoring​

Monitor key usage in your dashboard Set up alerts for suspicious activity Review last used timestamp regularly

Access Control​

Restrict API key usage to specific IP addresses (if available) Use role-based access control Limit key permissions (if granular permissions available)

Troubleshooting​

Key Not Working?​

  1. Check the key format: sk_live_... or sk_test_...
  2. Ensure it's in the correct header: Authorization: Bearer YOUR_KEY
  3. Verify the key hasn't been revoked
  4. Check your subscription status and credits

Lost Your Key?​

You cannot retrieve a lost key. You must:

  1. Create a new API key
  2. Update all services with the new key
  3. (Optional) Revoke the lost key for security

Next Steps​