Authentication

Three separate things go by the name "auth" on Drift, and keeping them apart saves a lot of confusion. The route gate decides whether a request reaches your function at all. The Deed primitives, JWT and KeyAuth, are what your handler uses to work out who is calling. Your Drift account is a third thing entirely: the session the CLI uses to talk to the platform. This page covers all three, in that order.

The route gate

A function's auth — declared on its Driftfile entry — is checked inside your slice: after the router hands the request over and the route is matched, and before the function subprocess is spawned. Nothing is gated at the platform edge: the edge forwards Authorization and X-API-Key through untouched, precisely so your slice can read them.

API keys

auth=apikey is the machine-to-machine gate: one shared secret per method and route, compared in constant time, stored by the slice and reloaded after a restart.

Managing keys

drift atomic auth set send-email s3cr3t-value
drift atomic auth set reports/daily s3cr3t-value --method get
drift atomic auth list send-email
drift atomic auth revoke send-email
drift atomic auth revoke reports/daily --method get

Keys are held per method + route. The route is the same identity the platform routes on: element/name for a function inside an element, the bare name otherwise. list shows a last-four fingerprint, never the key.

A configured key outranks the declaration

The effective mode is apikey whenever a key exists for the route, whatever the function declared. So drift atomic auth set locks down a live function that shipped as auth=none, with no redeploy, and revoke opens it back up.

The three refusals

The 503 is the one most people meet first: declaring auth=apikey and deploying, without running drift atomic auth set, closes the route to everyone including you.

Where the key rides

X-API-Key: <key> is the header to reach for. Authorization is accepted as well (bare, or with a Bearer  or ApiKey  prefix) for clients that cannot set a custom header.

JWT: issue and verify

Tokens are HS256, signed with a 32-byte key unique to your slice. You never see, set or rotate that key: signing and verification both happen inside the slice, and your function only ever holds the finished token. When you leave iss unset it is stamped with your slice's identity, and verification checks it, so a token minted by one slice fails at another.

Login → protected route

Both routes are auth=none. Login checks credentials and mints a token; the protected route verifies it. The gate has no token mode, so the check belongs in the handler, which is where you want it anyway, because that is the only place you can choose the status code, the error body, and what "authorised" means for this particular route.

Go

// Driftfile: name post:login, handler PostLogin
func PostLogin(body map[string]any, req drift.Request) (int, string, any, map[string]string) {
    user, ok := checkPassword(body["email"], body["password"])  // your check, against Backbone
    if !ok {
        return 401, "Unauthorized", map[string]any{"error": "bad credentials"}, nil
    }
    token, err := drift.Deed.JWT.Issue(drift.JWTClaims{
        Sub:    user.ID,
        Exp:    time.Now().Add(24 * time.Hour).Unix(),
        Custom: map[string]any{"role": user.Role},
    })
    if err != nil {
        return 500, "Internal Server Error", map[string]any{"error": "could not issue token"}, nil
    }
    return 200, "OK", map[string]any{"token": token}, nil
}

// Driftfile: name get:me, handler GetMe     // the handler is the gate
func GetMe(req drift.Request) (int, string, any, map[string]string) {
    token := strings.TrimPrefix(req.Headers["Authorization"], "Bearer ")
    claims, err := drift.Deed.JWT.Verify(token, drift.JWTVerifyOptions{})
    if err != nil {
        return 401, "Unauthorized", map[string]any{"error": err.Error()}, nil
    }
    return 200, "OK", claims.Custom, nil
}

Python

# Driftfile: name post:login, handler post_login
def post_login(body, req):
    user = check_password(body["email"], body["password"])
    if not user:
        return 401, "Unauthorized", {"error": "bad credentials"}
    token = drift.deed.jwt.issue(
        sub=user["id"],
        exp=int(time.time()) + 86400,        # 24h
        custom={"role": user["role"]},
    )
    return 200, "OK", {"token": token}

# Driftfile: name get:me, handler get_me
def get_me(req):
    token = req["headers"]["Authorization"].removeprefix("Bearer ")
    try:
        claims = drift.deed.jwt.verify(token)
    except drift.JWTError as e:
        return 401, "Unauthorized", {"error": e.reason}
    return 200, "OK", claims["custom"]

The token rides in the standard Authorization: Bearer <token> header. A browser frontend served from Canvas calls /api/me same-origin and adds that header, with no CORS in the way. Store the token however your client prefers.

Passwordless: KeyAuth

When you would rather not store passwords at all, the KeyAuth Deed primitive builds login on device key pairs (Ed25519). The device generates the pair; its public key is the identity. There is nothing to leak server-side: the slice sees public keys and signatures, and keeps neither a password nor a hash.

1. Challenge: drift.Deed.KeyAuth.Challenge(pubkey) mints a one-time nonce. Pair it with drift.Deed.JWT.SliceID() and send both to the device, which needs the slice's own identity to sign the next step.
2. Sign: the client signs the canonical {domain, nonce, pubkey, slice} JSON with its private key, which never leaves the device.
3. Verify: drift.Deed.KeyAuth.Verify(pubkey, sig, domain) checks the signature and returns one of your slice's ordinary JWTs.

// Driftfile: name post:auth/challenge, handler PostAuthChallenge
func PostAuthChallenge(body map[string]any, req drift.Request) (int, string, any, map[string]string) {
    nonce, err := drift.Deed.KeyAuth.Challenge(body["pubkey"].(string))
    if err != nil {
        return 400, "Bad Request", map[string]any{"error": err.Error()}, nil
    }
    // the device signs against this slice's own identity, so it has to be sent along with the nonce
    return 200, "OK", map[string]any{"nonce": nonce, "slice": drift.Deed.JWT.SliceID()}, nil
}

// Driftfile: name post:auth/verify, handler PostAuthVerify
func PostAuthVerify(body map[string]any, req drift.Request) (int, string, any, map[string]string) {
    token, err := drift.Deed.KeyAuth.Verify(body["pubkey"].(string), body["sig"].(string), "my-app")
    if err != nil {
        return 401, "Unauthorized", map[string]any{"error": "bad signature"}, nil
    }
    return 200, "OK", map[string]any{"token": token}, nil
}

The lifetimes and identities KeyAuth enforces

What comes back is an ordinary slice JWT, so the protected routes verify it exactly as they verify a password login's token: drift.Deed.JWT.Verify in the handler. Passwordless login slots in without changing anything downstream. Pair it with the Vault primitive for zero-knowledge account recovery.

Your Drift account

Everything above is auth for your app. This is the auth you meet first: the session the CLI holds against the platform. It shares no keys, tokens or storage with anything your slice runs.

The commands

Login and signup are capped at 10 attempts per minute per IP address.

Two-factor authentication

Drift speaks TOTP, the six-digit codes any authenticator app produces. Once a factor is enrolled, a correct password no longer returns a session: the platform answers with a short-lived challenge, and a code turns that challenge into tokens.

drift account mfa enrol
# add the secret to your app, type the code it shows
# ten recovery codes are printed once

drift account login
# Authentication code (or press enter to use a recovery code):

The token pair

Refresh is rotation-on-use: each refresh revokes the token presented and issues a replacement, recording the link between them. Replaying a spent token is read as a compromise and revokes every live token for the account, forcing a fresh login everywhere. The CLI does this for you: a 401 on any command triggers one refresh and one retry, invisibly.

Both login and refresh carry a per-workstation device_id. A refresh whose device does not match the one recorded at login is treated the same as replay: every live token for the account is revoked.

Personal access tokens and scopes

Your own session can do everything your account can. A CI pipeline or a script should not have to run under that, so an access token carries a narrower, named set of permissions and is revoked on its own, without touching your password.

drift account token create ci --scope slice:read --scope slice:write
drift account token list
drift account token revoke ci

The value is printed once, at creation. Drift stores only its hash, so there is no command that can show it again. Use it without ever logging in:

export DRIFT_TOKEN=drift_pat_...
export DRIFT_SLICE=my-slice
drift file apply

Revoking takes effect within about fifteen minutes: a personal access token is itself long-lived and opaque, and every call exchanges it for one of the ordinary 15-minute access tokens above before doing anything, so revoking stops new exchanges while letting one already in flight run out on its own. drift account token list shows every token you have minted, revoked and expired ones included, so "was there a credential that could do this, and when did it stop" always has an answer.

The same scopes back a second person on the account, not only a script: drift account member invite <email> adds a colleague who logs in as themselves and is granted exactly slice:read and slice:write. They deploy and operate; they cannot read or change your secrets, read your audit trail, mint a token, invite anyone else, or delete the account. Removing a member ends their access to your account, not their own account: their login, password and second factor stay theirs.

What lives on your disk

Atomic guide → · Deed reference → · SDK reference →