OAuth partner integrations

​

What the integration creates

• encrypted provider credential;
• independently configured gateway and model bindings; and
• runtime gateway token limited to the data-plane run scope.

​

Before you start

• the Client ID;
• the one-time Client secret; and
• the exact HTTPS redirect URI registered for the partner backend.

• protections:provision — Resolve providers, validate a provider key, discover models, run preflight, and provision resources atomically.
• protections:read — Read only protections created by this OAuth connection.
• protections:update — Update only protections created by this OAuth connection.
• protections:manage — Revoke, reactivate, or rotate credentials only for protections created by this OAuth connection.
• protections:read-logs — Read request metadata only for protection runtime tokens created by this OAuth installation. Request and response bodies are never exposed through OAuth.
• protections:read-spend — Read token usage and monetary spend only for protections created by this OAuth installation.
• offline_access — Renew access automatically with rotating refresh tokens. The integration must be authorized again after 90 days without a successful refresh.

​

OAuth endpoints

​

Choose an implementation path

​

Option A: Node or TypeScript SDK

​

Option B: Direct HTTP and OpenAPI

​

Connect once

import { OAuthPartnerClient, createPkce } from "@airctrl/sdk";

const oauth = new OAuthPartnerClient(
  process.env.AIRCTRL_CLIENT_ID!,
  process.env.AIRCTRL_CLIENT_SECRET!,
  {
    apiBaseUrl: process.env.AIRCTRL_API_ORIGIN!,
    webBaseUrl: process.env.AIRCTRL_WEB_URL!,
  },
);

​

1. Start authorization

const { verifier, challenge } = await createPkce();
const state = crypto.randomUUID();

await sessions.save(sessionId, {
  state,
  codeVerifier: verifier,
  expiresAt: Date.now() + 10 * 60_000,
});

const url = oauth.authorizationUrl({
  redirectUri: process.env.AIRCTRL_REDIRECT_URI!,
  scopes: [
    "protections:provision",
    "protections:read",
    "protections:update",
    "protections:manage",
    "protections:read-logs",
    "protections:read-spend",
    "offline_access",
  ],
  state,
  codeChallenge: challenge,
});

return redirect(url);

​

2. Handle the callback

const pending = await sessions.require(sessionId);
if (query.state !== pending.state) throw new Error("oauth_state_mismatch");
if (query.iss !== process.env.AIRCTRL_API_ORIGIN) throw new Error("oauth_issuer_mismatch");

const tokens = await oauth.exchangeCode({
  code: query.code,
  redirectUri: process.env.AIRCTRL_REDIRECT_URI!,
  codeVerifier: pending.codeVerifier,
});

await encryptedTokenStore.save(airctrlOrganizationId, tokens);

​

Protect one external key

​

1. Resolve the provider

const providers = await oauth.listProvisioningProviders(accessToken);
const provider = providers.find((candidate) => candidate.slug === selectedProviderSlug);
if (!provider) throw new Error("provider_unavailable");

​

2. Run preflight before sending the provider key

const preview = await oauth.preflightProtection(accessToken, {
  providerId: provider.provider_id,
  otel: false,
});

if (!preview.allowed) {
  return showAIRCTRLBlockers(preview.blockers, preview.quotas);
}

​

3. Validate the key and load live models

const providerKey = await partnerSecrets.require(selectedKeyId);
const catalog = await oauth.discoverProvisioningProviderModels(
  accessToken,
  provider.provider_id,
  providerKey,
);

if (catalog.invalidApiKey) throw new Error("provider_key_invalid");

​

4. Provision atomically

const protection = await oauth.provisionProtection(
  accessToken,
  idempotencyKey,
  {
    externalResourceId: selectedKeyId,
    providerId: provider.provider_id,
    providerKey,
    credentialLabel: `${selectedKeyName} key`,
    gatewayName: selectedKeyName,
    models: selectedModelIds,
    settings: {
      loggingEnabled: true,
      logBodies: false,
      guardrailMode: "redact",
    },
  },
);

await partnerSecrets.saveAIRCTRLRuntimeToken(
  selectedKeyId,
  protection.gatewayToken.plaintext!,
);

​

Use and manage the protected gateway

import { buildGatewayConnectionConfig } from "@airctrl/sdk/gateway-connections";

const connection = buildGatewayConnectionConfig(
  process.env.AIRCTRL_API_ORIGIN!,
  protection.gateway.slug,
);

const compatBaseUrl = connection.compatBaseUrl;

const protections = await oauth.listProtections(accessToken);

const updatedProtection = await oauth.updateProtection(accessToken, protection.protectionId, {
  gatewayName: "Support AI v2",
  models: ["model-standard", "model-vision"],
  settings: { rateLimitPerMin: 240 },
});

const logs = await oauth.listProtectionLogs(accessToken, protection.protectionId, {
  since: "2026-10-01T00:00:00.000Z",
  limit: 50,
});
const spend = await oauth.getProtectionSpend(accessToken, protection.protectionId, {
  since: "2026-10-01T00:00:00.000Z",
});

​

Choose internal logs or OpenTelemetry

​

Direct HTTP implementation

1. Read /.well-known/oauth-authorization-server and redirect the browser to its authorization_endpoint with response_type=code, exact redirect_uri, registered scopes, high-entropy state, and PKCE S256.
2. Exchange the callback code at POST /v1/oauth/token using HTTP Basic client authentication and a form-encoded body.
3. Call GET /v1/oauth/protections/providers with the OAuth bearer and resolve the provider by slug.
4. Call GET /v1/oauth/protections/preflight?providerId={providerId} before sending the key.
5. Call POST /v1/oauth/protections/providers/{providerId}/models with { "apiKey": ... } from the confidential backend.
6. Call POST /v1/oauth/protections with the OAuth bearer, JSON body, and a stable Idempotency-Key header.
7. Store the returned protectionId next to the external key ID. Use GET and PATCH /v1/oauth/protections/{protectionId} only for that protection.
8. Use the protection lifecycle endpoints to revoke, reactivate, or rotate only that external key. Runtime-token rotation and reactivation require a stable Idempotency-Key.
9. Poll GET /v1/oauth/protections/{protectionId}/logs and GET /v1/oauth/protections/{protectionId}/spend only when the App and installation grant the corresponding scopes.
10. Rotate at POST /v1/oauth/token with grant_type=refresh_token; revoke through POST /v1/oauth/revoke.

curl --request POST "$AIRCTRL_TOKEN_ENDPOINT" \
  --user "$AIRCTRL_CLIENT_ID:$AIRCTRL_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "code=$AIRCTRL_AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=$AIRCTRL_REDIRECT_URI" \
  --data-urlencode "code_verifier=$AIRCTRL_CODE_VERIFIER"

curl --fail-with-body \
  --header "Authorization: Bearer $AIRCTRL_ACCESS_TOKEN" \
  "$AIRCTRL_API_URL/oauth/protections/providers"

curl --fail-with-body \
  --header "Authorization: Bearer $AIRCTRL_ACCESS_TOKEN" \
  "$AIRCTRL_API_URL/oauth/protections/preflight?providerId=$AIRCTRL_PROVIDER_ID"

POST /v1/oauth/protections/providers/{providerId}/models
Authorization: Bearer {access-token}
Content-Type: application/json

{ "apiKey": "<server-side provider key>" }

POST /v1/oauth/protections
Authorization: Bearer {access-token}
Idempotency-Key: {stable-protection-operation-id}
Content-Type: application/json

{
  "externalResourceId": "partner-key-support",
  "providerId": "11111111-1111-4111-8111-111111111111",
  "providerKey": "<server-side provider key>",
  "credentialLabel": "Support AI key",
  "gatewayName": "Support AI",
  "models": ["model-standard"],
  "settings": {
    "loggingEnabled": true,
    "logBodies": false,
    "guardrailMode": "redact"
  }
}

GET    /v1/oauth/protections
GET    /v1/oauth/protections/{protectionId}
PATCH  /v1/oauth/protections/{protectionId}
GET    /v1/oauth/protections/{protectionId}/logs
GET    /v1/oauth/protections/{protectionId}/spend
POST   /v1/oauth/protections/{protectionId}/rotate-provider-key
POST   /v1/oauth/protections/{protectionId}/rotate-runtime-token
POST   /v1/oauth/protections/{protectionId}/revoke
POST   /v1/oauth/protections/{protectionId}/reactivate

​

Refresh and disconnect

const next = await refreshLock.run(airctrlOrganizationId, async () => {
  const current = await encryptedTokenStore.require(airctrlOrganizationId);
  const rotated = await oauth.refresh(current.refresh_token!);
  await encryptedTokenStore.compareAndSwap(current.refresh_token!, rotated);
  return rotated;
});

await oauth.revoke(current.refresh_token!);
await encryptedTokenStore.remove(airctrlOrganizationId);

​

Errors a partner must handle

• oauth_redirect_uri_invalid — The callback does not exactly match registration. Use the registered HTTPS URI verbatim.
• oauth_state_invalid / oauth_state_mismatch — State is missing, malformed, or different from the stored transaction. Abort and start a new authorization.
• oauth_authorization_request_expired — The pending consent request expired or was already decided. Start authorization again; do not reuse it.
• oauth_scope_insufficient — The token lacks the required delegated scope. Reconnect requesting only registered required scopes.
• oauth_access_not_allowed — The endpoint is not part of the OAuth surface. Do not substitute a PAT; use documented OAuth operations.
• subscription_inactive — The owning organization no longer has active product access. Active subscription, trial, and payment-retry (past_due) states qualify; other states must return to Billing before integration continues.
• provider_key_invalid — The provider rejected the supplied key. Ask the user to repair the key in the external platform.
• provider_model_not_available / provider_model_not_supported — A requested model is absent from the live catalog or AIRCTRL cannot safely route it. Refresh model discovery and let the user choose only supported IDs.
• provider_endpoint_not_configured / provider_validation_unavailable — Provider discovery or validation is temporarily unavailable. Do not persist the key; retry with bounded backoff.
• Preflight blockers — Subscription, entitlement, or quota prevents protection. Show blockers before sending the provider key.
• idempotency_key_invalid — The key is shorter than 16 characters or longer than 200. Generate a new stable operation key before sending the write.
• idempotency_key_reused / idempotency_operation_in_progress — The key was reused with a different body or the original transaction has not committed. Never change the body; reconcile or retry the identical request.
• idempotency_operation_superseded — A newer runtime-token operation already replaced the result of the retried lifecycle command. Keep the newest successful token and do not repeat the old operation with a new key.
• oauth_external_resource_already_protected — This connection already mapped the same stable external resource ID. Read the existing protections instead of creating a duplicate.
• oauth_gateway_protection_revoked / oauth_gateway_protection_connection_suspended — The protection cannot be updated or rotated in its current state. Reauthorize the connection when suspended, then call reactivate deliberately.
• oauth_project_unavailable / oauth_service_account_inactive / oauth_service_account_unrecoverable — The preserved internal project or Service Account cannot currently serve the connection. Stop automation and require an authorized AIRCTRL user to review the installation.
• otel_endpoint_required — The protection has no OTel configuration yet. Include endpoint the first time; later PATCH requests may omit it.
• otel_headers_invalid — The request exceeded 32 headers, used an invalid/forbidden name, or a value exceeded 2,048 characters. Correct the server-side OTel configuration.
• otel_not_available — Effective account entitlements do not enable OTel. Continue without OTel or let an authorized user review internal logs; do not mention internal entitlement grants.
• log_bodies_require_logging / otel_bodies_require_gateway_log_bodies — Enable gateway logging and body capture before requesting body export.
• 429, 500, 502, 503 — Temporary capacity or upstream failure. Retry with bounded backoff and the same idempotency key when provisioning.

​

Security checklist

• Keep all secrets and OAuth tokens in the confidential backend.
• Use exact HTTPS redirect URIs, PKCE S256, high-entropy state, and exact issuer validation.
• Resolve provider IDs from the registry instead of hard-coding them.
• Run preflight before transmitting a provider key.
• Treat externalResourceId and idempotency keys as stable per protection.
• Never log request authorization headers, provider keys, runtime gateway tokens, or OAuth token bodies.
• Revoke tokens on disconnect; do not delete AIRCTRL resources to simulate revocation.