🛡️Gatekeeper/ SDKs

API keys are the credential your customers' services present. This guide issues a scoped key with its own quota, validates it without a bearer token, exchanges it for a short-lived RS256 access token, and revokes it. The plaintext key is returned exactly once at creation; store it then, because the API only keeps a hash.

  1. Create a key with keys.create({ tenantId, scopes, quotaLimit, quotaPeriod }). The result carries plainTextKey (show once) and apiKey (the public record).

  2. Validate the raw key with keys.validate(key) - an unauthenticated call that returns the key's tenant, scopes, and status.

  3. Exchange the key for a signed RS256 bearer token with keys.token(key), then set it on the core for downstream calls.

  4. Revoke the key with keys.revoke(id) when it is compromised or rotated.

import { GatekeeperCore, KeysService } from '@orkait/sdk';
 
const core = new GatekeeperCore({ baseUrl: 'https://gatekeeper-api.example.workers.dev' });
core.setToken(ownerAccessToken); // a bearer with rights over the tenant
 
const keys = new KeysService(core);
 
// 1. Issue a scoped key with its own per-key quota.
const created = await keys.create({
  tenantId: 't_acme',
  name: 'ci-runner',
  scopes: ['read', 'usage:write'],
  quotaLimit: 10_000,
  quotaPeriod: 'day',
});
console.log('store this once:', created.plainTextKey);
const keyId = created.apiKey.id;
 
// 2. Validate the raw key (no bearer needed).
const validated = await keys.validate(created.plainTextKey);
console.log(validated.status, validated.scopes);
 
// 3. Exchange the key for a short-lived RS256 bearer token.
const { token, tokenType } = await keys.token(created.plainTextKey);
core.setToken(token); // tokenType is 'Bearer'
 
// 4. Revoke when rotating or on compromise.
await keys.revoke(keyId);