Authentication

The Gigadrive Network client resolves a credential in its constructor, before it sends anything. Pass one in, or set environment variables and let the client find them.

Credentials you pass in

Four combinations are recognized, each selecting a different OAuth 2.0 flow.

Client credentials are the common case:

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

const client = new GigadriveClient({
  clientId: process.env.GIGADRIVE_CLIENT_ID,
  clientSecret: process.env.GIGADRIVE_CLIENT_SECRET,
});

const { items } = await client.applications.list();

The client id is an API key ID and the secret is the string that key returned at creation. Both come from API keys. The client posts them to https://api.gigadrive.network/oauth2/token with HTTP Basic auth, then caches the access token it gets back.

Access tokens last 300 seconds. The client refreshes 30 seconds before expiry, or earlier for shorter tokens, since the margin is capped at half the lifetime. Concurrent callers share one in-flight refresh rather than each triggering their own.

Every constructor option

scopes applies to the authorization-code flow only, and it replaces the default set rather than adding to it. Requesting ['network:applications:read'] alone drops openid, profile, email and offline_access, so list the identity scopes again if you still want them. The names come from Scopes.

applicationId is not a credential. It supplies the default application for client.storage, which addresses buckets without repeating the application in every call.

Credentials detected from the environment

With no matching config field, the client walks this list and takes the first match.

Config always beats the environment, and the authorization-code flow has no environment branch: a callback is a function, so it can only be passed in code.

These are the seven variables the client reads:

A bearer token is never renewed. When it expires, requests fail with AuthenticationError and you have to build a new client.

Inside a deployed Function

Every deployed Function gets its own OAuth client, with GIGADRIVE_CLIENT_ID, GIGADRIVE_CLIENT_SECRET and GIGADRIVE_APPLICATION_ID injected at start. Row 6 of that table picks them up, so the constructor takes no arguments:

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

const client = new GigadriveClient();

export async function saveAvatar(userId: string, file: Blob): Promise<string> {
  const { url } = await client.storage.upload({
    bucket: 'avatars',
    key: `avatars/${userId}.png`,
    data: file,
  });

  return url;
}

That credential is scoped to the Function's own application and carries storage, sticky-session and runtime-cache permissions only. It cannot create applications or read environment variables. OIDC federation lists the exact scope set and what the platform injects.

On your own machine

gigadrive setup links the directory to an application, provisions an application-scoped key, and writes GIGADRIVE_CLIENT_ID, GIGADRIVE_CLIENT_SECRET and GIGADRIVE_API_BASE_URL into .env.local. Pass --rotate to revoke the previous key and mint a fresh one.

That key is deliberately narrow: it grants network:env_vars:read and nothing else. For anything beyond reading configuration, create a key with the scopes you need through client.apiKeys.create, described in Resources.