Authentication

Every call to the Gigadrive Network API carries Authorization: Bearer <token>. You get that token by exchanging an API key at POST /oauth2/token with the OAuth 2.0 client-credentials grant, which is the only grant the token endpoint supports.

The same header also accepts a user token issued by the Gigadrive account system, so a tool that signs a person in can call the API as that person. For automation, use an API key because a key is bound to an application rather than to somebody's account.

Getting a key

A key is application-scoped. Its actor is the application rather than you, so it reaches that application and the deployments, environment variables and buckets under it, and nothing else. There is no console screen for keys today, so the first one comes from the CLI:

gigadrive login   # device authorization flow against the Gigadrive account system
gigadrive setup   # links this directory to an application, then writes .env.local

gigadrive setup mints a key named cli-dev:<hostname>:<applicationId> carrying the single scope network:env_vars:read, and writes GIGADRIVE_CLIENT_ID, GIGADRIVE_CLIENT_SECRET and GIGADRIVE_API_BASE_URL into .env.local. Run it again with --rotate to revoke that key and mint a fresh one.

For anything wider, mint a key over the API with a token you already hold. The call needs platform:api_keys:write and access to the application:

curl -sS -X POST https://api.gigadrive.network/api-keys \
  -H "Authorization: Bearer $GIGADRIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ci",
    "applicationId": "0197b2f1-2f4a-7a0b-8a2d-222222222222",
    "scopes": ["network:deployments:trigger", "network:deployments:write"]
  }'

The response carries secret exactly once. No endpoint returns it again, and GET /api-keys?applicationId=... returns metadata only. Store it before you close the terminal.

Revoke a key with DELETE /api-keys/{apiKeyId}, which needs platform:api_keys:delete.

Exchanging the key for a token

client_id is the key's id, a UUID. client_secret is the secret you stored, which begins gdnet_secret_. Send them as HTTP Basic credentials or as client_id and client_secret body fields; Basic wins when both are present.

import { GigadriveClient } from '@gigadrive/sdk';

// Credentials come from GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET.
// The client exchanges them at /oauth2/token and refreshes 30 seconds before expiry.
const client = new GigadriveClient();

const { items, total } = await client.applications.list();
console.log(`${items.length} of ${total} applications`);

A successful exchange returns 200 with Cache-Control: no-store:

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "scope": "openid network:applications:read network:deployments:trigger"
}

Read scope rather than assuming: openid is always added, and any string on the key that is not a recognised scope is dropped instead of passed through.

Token lifetime

Tokens last 300 seconds and there is no refresh token. When one expires, exchange the key again.

Cache the token instead of minting one per call. The token endpoint takes no bearer header, so it is charged against the lower anonymous rate limit budget.

Revoking a key stops the next request made with a token derived from it, because the key is re-checked on every call. A token already in flight keeps working until it expires, so the longest a revoked key can still act is 5 minutes.

What is inside the token

Access tokens are RS256 JWTs. The protected header names its signing key with kid. Keys rotate, so select the verification key by the kid on the token you are checking rather than pinning one.

Two discovery endpoints are public and need no credential. GET /.well-known/openid-configuration publishes the token endpoint, the supported scopes and the supported claims; GET /.well-known/jwks.json publishes the signing keys. Both are cacheable for 5 minutes. The issuer advertises client_credentials as its only grant and exposes no authorization, userinfo or revocation endpoint.

When the exchange fails

The token endpoint answers in the RFC 6749 shape rather than the API's usual error body, so it has both an error code and an error_description.

Everything else on the API uses the single-field body described in Errors, which also explains why an entirely missing Authorization header comes back as a 422 rather than a 401.