Authentication

Figgshield has three ways in, for three purposes:

Purpose	Mechanism
Sign in to the web app	SSO — Google, Apple or GitHub
Connect Claude or the Claude Code CLI	OAuth 2.1 (browser sign-in, PKCE)
CLI header or the REST API	Personal API key (Authorization: Bearer figg_...)

There is no email/password sign-in and no email one-time-code step — sign-in is SSO only.

Signing in (SSO)

The web app authenticates with one of three identity providers: Google, Apple and GitHub. Sign-in creates or links your account by email and sets an HttpOnly session cookie named token; the app uses that cookie for account, plan and key management. There is nothing to configure — pick a provider on the sign-in screen.

GET /authentication/social/config/ reports which providers are available, so the app can hide any that are not configured:

curl https://api.figgshield.ai/authentication/social/config/

{ "google": true, "apple": true, "github": true }

The current user is read with GET /authentication/me/ (session cookie), and POST /authentication/logout/ clears the cookie.

OAuth for the connector and CLI

Adding Figgshield to Claude (as a connector) or the Claude Code CLI uses OAuth 2.1, not a session cookie. Figgshield is the authorization server; Google, Apple and GitHub are the upstream identity providers it federates to. You never paste a token — the client runs the flow:

1. The client requests https://api.figgshield.ai/mcp unauthenticated and receives 401 with a WWW-Authenticate header pointing at the protected-resource metadata.
2. It discovers the authorization server, then opens a browser for you to sign in (SSO) and approve the scopes figgshield:read and figgshield:write.
3. It exchanges an authorization code (PKCE, S256) for a JWT access token and refreshes it automatically.

Discovery documents:

Document	URL
Protected resource metadata (RFC 9728)	https://api.figgshield.ai/.well-known/oauth-protected-resource
Authorization server metadata (RFC 8414)	https://api.figgshield.ai/.well-known/oauth-authorization-server
JWKS	https://api.figgshield.ai/jwks.json

See MCP server & tools and Claude Code CLI for the client-side steps. Claude registers itself automatically (Dynamic Client Registration), so private connectors need no manual client setup.

Personal API keys

An API key authenticates the Claude Code CLI (as a header) and the REST API without a browser flow. A key acts with the same permissions as the account that owns it.

Create keys in the app under Account → API keys. A key looks like figg_ followed by 40 hex characters:

figg_1f2e3d4c5b6a79880716253443526170817263f4

The full secret is shown once, at creation — Figgshield stores only a SHA-256 hash and the first 12 characters as a display prefix. If you lose a key, revoke it and create a new one. An account can hold at most 20 active keys.

Send the key on every request with the Authorization: Bearer header (or X-API-Key):

curl https://api.figgshield.ai/api/models/ \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"

For the Claude Code CLI, pass it when you add the server:

claude mcp add --transport http figgshield https://api.figgshield.ai/mcp \
  --header "Authorization: Bearer figg_your_api_key_here"

A revoked or unknown key returns 401 with the machine code invalid_api_key:

{ "error": "invalid_api_key", "detail": "This API key is invalid or has been revoked." }

Managing keys over the REST API

Key management also works over the API, so keys can rotate keys. Each call accepts a session cookie or an API key.

# Create
curl https://api.figgshield.ai/api/keys/create/ -X POST \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline" }'

# List
curl https://api.figgshield.ai/api/keys/ \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"

# Revoke
curl https://api.figgshield.ai/api/keys/<uuid>/revoke/ -X POST \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"

Create returns 201 and is the only response that ever contains the full key. List returns the standard envelope with uuid, name, prefix, last_used_at, revoked and created_at — never the secret. Revoke returns 200 {"revoked": true}, is idempotent, and frees the key from the 20-key cap.

Session cookies (browser)

The web app authenticates with the HttpOnly token cookie set at SSO sign-in and cleared by POST /authentication/logout/. Browser clients send it automatically with credentials: "include". The cookie is for the account screens; programmatic clients should use OAuth (for MCP) or an API key (for the CLI header and REST).