Authentication & keys

Overview

Graphon has one credential: the API key. The same key works on the Graphon API, on the Storage API, and in S3 tools such as the AWS CLI and boto3. A key belongs to one workspace. It has a role, and it covers every bucket in the workspace.

An API key looks like gak_GAK1a8Xk2mQ9pL0vT4cZ.Qm9…. Graphon shows it once, when you create it. Lists show a masked key, such as gak_GAK1a8Xk2mQ9pL0vT4cZ.••••.

Roles

Personal and workspace keys

Each key has an owner. A personal API key belongs to you. A workspace API key belongs to the workspace. Use a workspace key for CI jobs, servers, and agents that must keep working when a person leaves.

An Admin workspace key does not count as an Admin for the last-Admin rule. It cannot restore a deleted workspace.

Create a key

In the app, open Settings → API keys for a personal key, or Settings → Workspace API keys for a workspace key. Or use the CLI. Copy the key when Graphon shows it, and store it in a secret manager.

# A personal API key. It gets your role unless you pass --role.
graphon api-keys create --name "Local CLI"

# A workspace API key (Admins only). It gets viewer unless you pass --role.
graphon api-keys create --name "ci" --owner workspace --role editor

Send the key

Send the whole key as a Bearer token. The same header works on the Graphon API and on the Storage API.

export GRAPHON_API_KEY="gak_..."

# Graphon API
curl \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/members" \
  --header "Authorization: Bearer $GRAPHON_API_KEY"

# Storage API
curl \
  --url "https://storage.beta.graphon.sh/v1/workspaces/$GRAPHON_WORKSPACE_ID/buckets" \
  --header "Authorization: Bearer $GRAPHON_API_KEY"

S3 credentials

S3 tools need two values. Both come from the API key. No server call is needed.

The access key ID is not secret. It appears in S3 error messages and logs, so you can match them to a key. us-east-1 is only the signing region. Your data stays in the region that you chose for the bucket.

Replace wspq7ws2np5l8z4 in the examples with your workspace ID. The endpoint must name the workspace that owns the key. JSON calls use the bare storage host. S3 uses the workspace host with path-style addressing.

In the app

On the page that shows a new key, turn on Show S3 credentials. The page shows the access key ID, the secret access key, the endpoint, and the region. Like the key, they are shown only once.

With the CLI

graphon s3-credentials reads the key from GRAPHON_API_KEY or --token. It prints shell exports for the AWS tools.

eval "$(graphon s3-credentials)"
aws s3 ls

To keep the key out of AWS files, add a profile that runs the CLI as a credential process. The AWS CLI and the AWS SDKs then read the values from the CLI.

# Replace wspq7ws2np5l8z4 with your workspace ID.
# ~/.aws/config
[profile graphon]
credential_process = graphon s3-credentials --format process
endpoint_url = https://wspq7ws2np5l8z4.storage.beta.graphon.sh
region = us-east-1
s3 =
  addressing_style = path

aws s3 ls --profile graphon

In code

Split the key when you build an S3 client.

# Replace wspq7ws2np5l8z4 with your workspace ID.
import os

import boto3
from botocore.config import Config

api_key = os.environ["GRAPHON_API_KEY"]
access_key_id = api_key.split("_", 1)[1].split(".")[0]

s3 = boto3.client(
    "s3",
    endpoint_url="https://wspq7ws2np5l8z4.storage.beta.graphon.sh",
    region_name="us-east-1",
    aws_access_key_id=access_key_id,
    aws_secret_access_key=api_key,
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

// Replace wspq7ws2np5l8z4 with your workspace ID.
import { S3Client } from '@aws-sdk/client-s3';

const apiKey = process.env.GRAPHON_API_KEY;
if (!apiKey) throw new Error('Set GRAPHON_API_KEY.');
const accessKeyId = apiKey.split('_')[1].split('.')[0];

const s3 = new S3Client({
  endpoint: 'https://wspq7ws2np5l8z4.storage.beta.graphon.sh',
  region: 'us-east-1',
  forcePathStyle: true,
  credentials: { accessKeyId, secretAccessKey: apiKey },
});

Presigned URLs

A presigned URL lets anyone who has it send one request for one object, with no key. Use one to share a file for a short time, or to let a browser upload a file.

• Get one from the Storage API with Presign an S3 request, or sign one with your S3 SDK.
• The URL is signed with your key. It shows the access key ID, which is not secret.
• A URL from the presign route lasts 15 minutes, or until your key expires if that is sooner.
• The signature fixes the method, workspace host, bucket name, and object key.
• Rename changes future URLs. An old name-based URL can address another bucket if that name is reused in the workspace. Current access checks still apply.
• When you revoke the key, every URL that it signed stops working.

url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "reports", "Key": "finance/q3-report.pdf"},
    ExpiresIn=900,
)

Temporary keys

The app and the CLI make temporary keys for you. You never create one. A temporary key starts with gtk_, acts with your role, and lasts 15 minutes. It works only on the Storage API and in S3. The CLI makes one after graphon login. A script that has an API key sends the API key directly.

When a change takes effect

If Graphon storage cannot be reached when you revoke a key, Graphon retries until storage accepts the change. Storage keeps no member or session data, so a temporary key can keep working for up to 15 minutes after these changes. This limit is by design.

Rotate a key

Create a new key, deploy it, then revoke the old key.

graphon api-keys create --name "Local CLI v2"
# Deploy the new key, then revoke the old one.
graphon api-keys revoke <oldKeyId>

See also

The Authentication reference covers the header format and the authentication errors.