API keys

An API key is a client-credentials pair bound to exactly one application. Use one when a machine needs to act on that application, such as a CI job that deploys or a script that reads environment variables.

What a key carries

The secret is gdnet_secret_ followed by 32 bytes of base64url entropy, so a leaked key is recognisable in logs and to secret scanners.

Creating a key

Keys are created through the API, the SDK, or the console. The gigadrive CLI has no command for them.

Creating, listing and revoking keys all require a user-backed token from Gigadrive IDP. A minted key can never hold a platform:api_keys: scope, which means an API key cannot create another API key. That is deliberate: it stops a leaked key from minting a wider one.

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

// A user access token from Gigadrive IDP, carrying platform:api_keys:write.
const client = new GigadriveClient({ bearerToken: process.env.GIGADRIVE_ACCESS_TOKEN });

const key = await client.apiKeys.create({
  name: 'ci-deploy',
  applicationId: '0197b2f1-2f4a-7a0b-8a2d-222222222222',
  scopes: ['network:deployments:read', 'network:deployments:trigger'],
});

// key.secret is returned exactly once.
console.log(key.id, key.secret);

Three rules apply to the scopes you ask for. An unknown scope returns 400. A scope you do not hold yourself returns 403 with Requested scope '<scope>' exceeds your own access. Anything starting with platform:api_keys: returns 400. Scopes lists the catalogue.

The key's actor is the application, not you. It keeps working after you stop being involved, and it can reach nothing outside that application.

In the console

1. Open API keys

   Open the application, go to Settings, then select API keys.

2. Create the key

   Select Create API key, then name it, grant scopes from the grouped picker, and choose an expiry: 30 days, 60 days, 90 days, 1 year, or No expiration.

3. Copy the credentials

   The client ID, client secret, and token endpoint are shown once, in a dialog you cannot reopen. Copy the secret before closing it.

A non-expiring key is console-only. The API and the SDK always set an expiry, 90 days by default, even when you omit expiresAt.

Creating or deleting a key from the console requires credentials proven within the last 15 minutes, the same re-authentication window that guards the rest of the security page.

Using a key

Exchange the key for a bearer token at the api.gigadrive.network token endpoint, then send that token on the resource request. client_id is the key ID and client_secret is the gdnet_secret_ string.

curl -X POST https://api.gigadrive.network/oauth2/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "0197b2fa-b4c6-7561-8db2-aaaaaaaaaaaa",
    "client_secret": "gdnet_secret_..."
  }'

The token lasts 300 seconds and there is no refresh token. The SDK handles the exchange and the renewal when you pass clientId and clientSecret. Authentication covers the endpoint in full, including its error codes.

Listing and revoking

GET /api-keys?applicationId=<uuid> returns key metadata for one application, never secrets. DELETE /api-keys/{apiKeyId} revokes a key and returns 204. The console's API keys settings page lists and deletes the same keys.

Revocation stops new tokens immediately. Tokens already issued from that key stay valid until they expire, so plan for up to five minutes of residual access.

Rotation

There is no rotate endpoint. Rotation is three steps: create a second key with the same scopes, move your clients onto it, then delete the first. Because keys expire after 90 days by default, put that sequence in your calendar or set expiresAt to a date you will notice.