Skip to main content

UC-014 — API Key Management

FieldValue
IDUC-014
GoalCreate, list and revoke API Keys for your account
ChannelAll
ComplexityBasic
Estimated time5 minutes
APIs involvedGET /api/partner-gateway/v1/authentication, POST /api/partner-gateway/v1/authentication, DELETE /api/partner-gateway/v1/authentication

Real-world scenarios​

  • Developer onboarding: The team lead creates a new dedicated API Key for a newly hired developer, limiting access to the staging environment only.
  • Periodic key rotation: FinSecure rotates its API Keys every 90 days as required by internal security policy.
  • Revoke a compromised key: A developer accidentally committed an API Key to a public repository and needs to revoke it immediately.

Management flow​

The diagram shows the complete API Key lifecycle: creation, listing and revocation.

Prerequisites​

  • Active account on the Qlara platform
  • At least one existing API Key to authenticate management calls
  • Admin permissions on your account

Step 1 — Create a new API Key​

Call the creation endpoint to generate a new key.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "staging-dev-marco",
    "description": "Chiave per ambiente staging - Marco Rossi"
  }'

Response — Key created​

{
  "id": "key_a1b2c3d4e5f6",
  "name": "staging-dev-marco",
  "description": "Chiave per ambiente staging - Marco Rossi",
  "apiKey": "pg_live_9f8e7d6c5b4a3210...",
  "createdAt": "2026-04-09T10:00:00+02:00",
  "status": "ACTIVE"
}

:::warning Save the key immediately The apiKey field is shown only at creation time. Copy it and store it in a secret manager (e.g. Vault, AWS Secrets Manager). It will not be recoverable afterwards. :::

Behind the scenes — Key generation
  1. Validation: The gateway verifies that the request comes from a user with admin permissions.
  2. Generation: A cryptographically secure token (256 bit) is generated with a pg_live_ prefix for easy identification.
  3. Hashing: The key is hashed (bcrypt) before storage -- the gateway only stores the hash, not the plaintext value.
  4. Association: The key is linked to the account and configured permissions.

Step 2 — List active keys​

Retrieve the list of all API Keys associated with your account.

curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Key list​

{
  "keys": [
    {
      "id": "key_a1b2c3d4e5f6",
      "name": "staging-dev-marco",
      "status": "ACTIVE",
      "createdAt": "2026-04-09T10:00:00+02:00",
      "lastUsedAt": "2026-04-09T14:30:00+02:00"
    },
    {
      "id": "key_z9y8x7w6v5u4",
      "name": "production-main",
      "status": "ACTIVE",
      "createdAt": "2026-01-15T09:00:00+01:00",
      "lastUsedAt": "2026-04-09T15:00:00+02:00"
    }
  ]
}

:::tip Monitor lastUsedAt The lastUsedAt field helps you identify unused keys. A key not used for months may be a candidate for revocation. :::

Step 3 — Revoke a compromised key​

Immediately delete a key that should no longer be used.

curl -X DELETE https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "id": "key_a1b2c3d4e5f6"
  }'

Response — Key revoked​

{
  "id": "key_a1b2c3d4e5f6",
  "status": "REVOKED",
  "revokedAt": "2026-04-09T15:30:00+02:00"
}
Behind the scenes — What happens after revocation
  1. Immediate invalidation: The key is marked as REVOKED in the Key Store. All subsequent requests with this key will receive 401 Unauthorized.
  2. Cache propagation: The invalidation propagates to caching nodes within 30 seconds.
  3. Audit log: The revocation event is recorded in the audit log with timestamp, IP and the user who performed the operation.
  4. No rollback: Revocation is irreversible. To re-enable access, create a new key.

Expected result​

StepActionResult
1POST /authenticationNew API Key created, status: "ACTIVE"
2GET /authenticationFull list of keys with lastUsedAt
3DELETE /authenticationKey revoked, status: "REVOKED"

Complete end-to-end example​

Scenario FinSecure: quarterly key rotation.

# 1. Create the new key
NEW_KEY=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "production-q2-2026",
    "description": "Chiave produzione Q2 2026"
  }' | jq -r '.apiKey')

echo "Nuova chiave: $NEW_KEY"

# 2. Verify the new key works
curl -s -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "X-Api-Key: $NEW_KEY" | jq '.keys | length'

# 3. Revoke the old key
curl -s -X DELETE https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $NEW_KEY" \
  -d '{"id": "key_old_q1_2026"}' | jq .

Variants​

Create a key with expiration​

Add an expiresAt field to create keys with automatic expiration:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "temp-contractor",
    "description": "Chiave temporanea per consulente esterno",
    "expiresAt": "2026-06-30T23:59:59+02:00"
  }'

Common errors​

401 Unauthorized — Invalid key​

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Solution: Verify that the X-Api-Key header is present and that the key used to manage other keys is still active.

403 Forbidden — Insufficient permissions​

{
  "status": "fail",
  "data": {
    "authorization": "Insufficient permissions to manage API keys"
  }
}

Solution: Only users with the admin role can create or revoke keys. Contact your account administrator.

Next steps​

References​