API Authentication: Supabase, Cognito, and Rolling Your Own

What you'll learn

Part 11 answered which header and which scheme — Bearer, cookies, API keys, HMAC. It deliberately stopped short of the harder question: where does the token come from, and who decides it's real? That is this part.

Two managed answers dominate, and they are genuinely different products with different failure modes. Then there's the third answer — issue your own — which is more defensible than the internet suggests, and more work than its advocates admit.

• Supabase Auth — how the token is signed, how to verify it in an API that is not Supabase, why app_metadata and user_metadata are not interchangeable, and where Row Level Security fits.
• Cognito — user pools, groups, custom attributes, the ID-token-versus-access-token trap, and machine-to-machine with client credentials.
• Three production systems — CargoNaut on Supabase behind a shared Lambda Authorizer; JunctionNet on Cognito behind API Gateway's native authorizer; via's transport backend issuing its own JWTs in NestJS. Same problem, three shapes.
• The parts that bite — the authorizer context contract, refresh-token rotation, authorizer caching, and the five failures that show up in real incidents.

Authentication is three decisions

Every design in this article is a different set of answers to the same three questions. Getting them separate in your head makes the rest straightforward:

1. WHO ISSUES the token?      Supabase GoTrue │ Cognito │ your own login endpoint
        │                     — owns passwords, MFA, reset, email verification
        ▼
2. WHO VERIFIES it?           the API gateway │ a custom authorizer │ your app process
        │                     — signature, issuer, audience, expiry
        ▼
3. WHAT DOES THE REQUEST      a verified identity: user id, tenant, role/scopes
   CARRY ONWARD?              — and NOTHING the caller can influence

The second and third decisions are where systems go wrong. Issuing tokens is a solved problem you can buy. Verifying them correctly on every route, and turning "this token is valid" into "this caller may do this to this tenant's data", is the part you own no matter which provider you pick.

How Supabase Auth works

Supabase Auth (the service is called GoTrue) is a hosted identity provider bolted onto your Postgres database. Users live in an auth.users table you don't own. On login it returns two things: a short-lived access token — a JWT, about an hour by default — and a long-lived refresh token.

A decoded Supabase access token looks like this:

{
  "iss": "https://abcdefgh.supabase.co/auth/v1",
  "sub": "9f1c…",                # the auth user's UUID — NOT your app user id
  "aud": "authenticated",
  "exp": 1735689600,
  "email": "maria@acme.com",
  "role": "authenticated",       # a POSTGRES role, not your app role
  "app_metadata":  { "org_id": "…", "role": "manager" },
  "user_metadata": { "display_name": "Maria" }
}

Two things in there are routinely misread, and both are security-relevant:

Two keys, two very different powers

Verifying a Supabase token in your own API

If every request went through Supabase's own PostgREST endpoint, you'd never write this code. The moment you put a real API in front — Lambda, a container, anything — you become the verifier. Supabase supports two signing schemes and you will meet both:

CargoNaut's authorizer handles both, and the interesting part is what it checks beyond the signature:

def _verify_supabase_jwt(token: str) -> dict:
    import jwt
    alg = (jwt.get_unverified_header(token).get("alg") or "").upper()

    if alg.startswith("HS"):
        # Legacy shared secret. Possession of the per-stage secret is the gate.
        payload = jwt.decode(
            token, os.environ["SUPABASE_JWT_SECRET"], algorithms=["HS256"],
            audience="authenticated",
            options={"require": ["sub", "exp", "iat"]},
        )
    else:
        from jwt import PyJWKClient
        supabase_url = os.environ["SUPABASE_URL"].rstrip("/")
        expected_iss = f"{supabase_url}/auth/v1"

        # Pin the issuer BEFORE trusting the token: a valid signature from
        # somebody else's Supabase project is still somebody else's user.
        iss = (jwt.decode(token, options={"verify_signature": False}).get("iss") or "").rstrip("/")
        if iss != expected_iss:
            raise ValueError(f"token issuer {iss!r} is not this stage's project")

        client = _jwks_clients.setdefault(expected_iss, PyJWKClient(f"{expected_iss}/.well-known/jwks.json"))
        payload = jwt.decode(
            token, client.get_signing_key_from_jwt(token).key,
            algorithms=["ES256", "RS256"],
            audience="authenticated", issuer=expected_iss,
            options={"require": ["sub", "exp", "iat"]},
        )

Four defences, each closing a real hole:

Claims are not your user table

The token's sub is a Supabase auth UUID. Your application has its own users — with a tenant, a business role, a status, foreign keys pointing at them. Those are two different identities, and the join between them belongs in exactly one place.

def _resolve_user_from_sub(sub: str) -> dict | None:
    """Resolve the stable app identity and business role for a JWT subject."""
    with _get_db().connect(readonly=True) as session:
        row = session.execute(
            text("SELECT id, org_id, role::text AS role "
                 "FROM users WHERE supabase_auth_id = :sub LIMIT 1"),
            {"sub": sub},
        ).fetchone()
        return None if row is None else {
            "id": str(row.id), "org_id": str(row.org_id), "role": str(row.role),
        }

The database row wins over the claim, and that ordering matters. A token issued an hour ago still carries the role the user had an hour ago. Someone demoted five minutes ago presents a technically valid token asserting admin. Reading the role from your own table means a permission change takes effect on the next request instead of the next login.

Row Level Security: the other half

Supabase's real distinguishing feature isn't the login screen — it's that authorization can live in the database. RLS policies are evaluated against the JWT's Postgres role and its claims, so a query from the browser is filtered by the same rules as one from your API:

alter table shipments enable row level security;

-- a user only sees rows in their own org
create policy "shipments are org-scoped" on shipments
  for select using (
    org_id = ((auth.jwt() -> 'app_metadata') ->> 'org_id')::uuid
  );

How Cognito works

Cognito is two unrelated products behind one name, and confusing them wastes a week:

A user pool gives you three levers for carrying authorization data:

• Groups — arrive as a cognito:groups array claim. This is how JunctionNet models roles: JunctionNetAdmin, OrganizationAdmin, Member, Seller, Customer.
• Custom attributes — custom:organization, custom:branches, custom:applications. Set at sign-up or by an admin. Immutable once created as a schema field, so name them carefully.
• Resource servers and scopes — OAuth2 scopes for machine callers. More on that below.

ID token or access token?

Cognito hands back three tokens and most teams pick the wrong one, for a reason that is genuinely the fault of the design.

So the purist answer is "use the access token", and then you discover your tenant lives in custom:organization, which the access token does not carry. That is exactly why JunctionNet's client-side helper returns the ID token:

auth_response = self.cognito_client.initiate_auth(
    AuthFlow="USER_PASSWORD_AUTH",
    AuthParameters={
        "USERNAME": config.username,
        "PASSWORD": config.password,
        "SECRET_HASH": secret_hash,   # required when the app client has a secret
    },
    ClientId=config.client_id,
)
token = auth_response['AuthenticationResult']['IdToken']   # ← the pragmatic choice
return AuthenticationResult(token, "Bearer")

That is a defensible engineering decision, not a mistake — but it is a decision, so make it deliberately and write down the consequences:

• Your authorizer must pin aud to your app client id and check token_use == "id". An ID token is scoped to a client, not to an API, so audience validation is the only thing keeping another app's ID token out.
• You inherit the ID token's lifetime and its larger payload in every request header.
• The clean alternative is a pre-token-generation Lambda trigger, which can add custom claims to the access token. If you're starting fresh, do that instead.

Machine-to-machine with client credentials

Human logins and service callers should not share a mechanism. Cognito's answer is a resource server that declares custom scopes, plus an app client allowed to use the client_credentials grant — no user involved:

def authenticate(self, config: AuthConfig) -> AuthenticationResult:
    token_url = f"https://{config.domain}/oauth2/token"
    encoded = base64.b64encode(f"{config.client_id}:{config.client_secret}".encode()).decode()

    response = requests.post(
        token_url,
        headers={"Authorization": f"Basic {encoded}",
                 "Content-Type": "application/x-www-form-urlencoded"},
        data={"grant_type": "client_credentials"},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()
    return AuthenticationResult(data["access_token"], "Bearer",
                                expires_in=data.get("expires_in"))

The resulting access token carries scope: "documents/read documents/write" and no sub for a human. Your API authorizes on the scope. This is strictly better than handing a service a user account and a password, which is the thing it replaces.

CargoNaut — Supabase behind one shared Lambda Authorizer

CargoNaut has a dozen SAM services on one HTTP API domain, and three kinds of caller: people in a browser, partners with API keys, and n8n automations posting callbacks. Rather than teach every service about all three, there is one authorizer Lambda, deployed by the platform, whose ARN every service reads from SSM:

Auth:
  DefaultAuthorizer: LambdaAuthorizer        # deny by default, everywhere
  Authorizers:
    LambdaAuthorizer:
      FunctionArn: !Sub '{{resolve:ssm:/CargoNaut/${Stage}/platform/authorizer_function_arn}}'
      AuthorizerPayloadFormatVersion: "2.0"
      EnableSimpleResponses: true              # {isAuthorized, context} — no IAM policy
      Identity:
        Headers: [ Authorization ]         # ← also the cache key. Remember this.
        ReauthorizeEvery: 300

One function, one handler(), three branches on the scheme:

def handler(event, context):
    headers   = event.get("headers", {})
    route_arn = event.get("routeArn", event.get("methodArn", ""))
    auth      = headers.get("authorization", "")

    if auth.startswith("Bearer "):  return _handle_jwt(auth[7:], route_arn)
    if auth.startswith("ApiKey "):  return _handle_api_key(auth[7:].strip(), event, route_arn)
    if headers.get("x-api-key"):    return _handle_api_key(headers["x-api-key"], event, route_arn)
    if headers.get("x-signature"): return _handle_internal(event, route_arn)
    return _deny(route_arn)

Every branch converges on the same output: a resolved org_id, a principal, a role and a scope list, handed downstream in the authorizer context. Services never parse a token. They read a struct.

The bodyless-authorizer problem

One constraint shapes the whole design and surprises everyone the first time: API Gateway never sends the request body to a Lambda authorizer — not in payload format 1.0, not in 2.0. So a cross-org machine credential, which must name the tenant it is acting for, has nowhere to put it except a header:

# An all-org M2M key can write to ANY tenant, so it is restricted to one route
# and must name its target org in a header the authorizer can actually see.
M2M_ALLOWED_ROUTE_SUFFIXES = ("/n8n/tracking-result",)

if result.get("all_org"):
    if not any(route_arn.endswith(s) for s in M2M_ALLOWED_ROUTE_SUFFIXES):
        return _deny(route_arn)          # out-of-scope route for this credential
    org_id = (event.get("headers") or {}).get("x-org-id")
    if not org_id:
        return _deny(route_arn)
    return _allow(route_arn, org_id, "m2m-api-key", auth_type="api_key", …)

JunctionNet — Cognito, the native authorizer, and a context middleware

JunctionNet gets to skip the custom authorizer: API Gateway has a built-in COGNITO_USER_POOLS authorizer that validates the signature, issuer, expiry and audience for you, then drops the claims into the event. The application's job starts after that, in a Powertools middleware that runs before every handler:

def inject_organization_user_context(app, next_middleware):
    # 1️⃣ Cognito claims — the gateway already verified this token.
    claims = app.current_event.get("requestContext", {}).get("authorizer", {}).get("claims")

    if claims:
        user_context = OrganizationUserContext(
            organization      = claims.get("custom:organization"),
            user_id           = claims.get("sub"),
            username          = claims.get("cognito:username"),
            user_email        = claims.get("email", ""),
            user_groups       = _normalize_to_list(claims.get("cognito:groups")),
            branches          = _normalize_to_list(claims.get("custom:branches")),
            user_applications = _normalize_to_list(claims.get("custom:applications")),
            environment       = env_vars.STAGE,
            application       = env_vars.APPLICATION,
        ).derive_roles()

derive_roles() is where a Cognito group becomes an application concept, in one place instead of scattered through handlers:

def derive_roles(self):
    groups = set(self.user_groups)
    self.is_jnet_admin            = "JunctionNetAdmin" in groups
    self.is_organization_admin    = "OrganizationAdmin" in groups
    self.is_organization_member   = "Member" in groups
    self.is_organization_seller   = "Seller" in groups
    self.is_organization_customer = "Customer" in groups
    return self

The middleware then falls back through a documented priority list for callers that aren't browser users — service tokens, static API keys, legacy webhook headers — each producing the same OrganizationUserContext. One shape reaches the handler regardless of how the caller authenticated, which is the same win CargoNaut gets from its authorizer context.

via — NestJS, self-issued JWTs, guards and refresh tokens

The transport backend has no managed IdP. It owns its users table, hashes passwords with bcrypt, and signs its own tokens. Login is a password check followed by two token issues:

const payload = { email: user.email, sub: user.id, role: user.role, agencyId: user.agencyId };

const accessToken  = this.jwtService.sign(payload);          // HS256, short-lived
const refreshToken = await this.generateRefreshToken(user.id); // opaque, in the DB

The two tokens are deliberately different kinds of thing. The access token is a signed, stateless JWT. The refresh token is an opaque random string with a row behind it, which is what makes it revocable:

private async generateRefreshToken(userId: string): Promise<string> {
  const token = this.generateRandomToken();
  const expiresAt = new Date();
  expiresAt.setDate(expiresAt.getDate() + 7);
  await this.refreshTokenRepository.save(
    this.refreshTokenRepository.create({ userId, token, expiresAt }),
  );
  return token;
}

private generateRandomToken(): string {
  // 256 bits of CSPRNG entropy — unguessable, unlike the old Math.random token.
  return randomBytes(32).toString('hex');
}

Verification is a Passport strategy. Note what validate() does after the signature checks out — it loads the user again:

export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(…) {
    super({
      jwtFromRequest:  ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,          // never true. not even in dev.
      secretOrKey:      getJwtSecret(),
    });
  }

  async validate(payload: any) {
    const user = await this.usersService.findOne(payload.sub);
    if (!user) throw new UnauthorizedException('User not found');
    // the request's principal comes from the DB, not from the token body
    return { id: user.id, email: user.email, role: user.role,
             agencyId: user.agencyId, terminalId: user.terminalId ?? null };
  }
}

That's the same choice CargoNaut makes in its authorizer, reached independently: a deleted or demoted user stops working on the next request, not at the next token expiry.

Deny by default, opt out explicitly

The guard is registered globally, so a new controller is protected the moment it exists. Only an explicit decorator opens a route:

export class JwtAuthGuard extends AuthGuard('jwt') {
  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(), context.getClass(),
    ]);
    return isPublic ? true : super.canActivate(context);
  }
}

// public.decorator.ts — the opt-out is one word, and it's greppable
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Side by side

Read down the last two rows and the trade is obvious. CargoNaut and JunctionNet bought passwords, MFA, reset flows and email verification, and pay for it with a verification layer they had to write and a provider they're coupled to. via owns every one of those flows — which is why auth.service.ts is 500 lines containing reset codes, verification emails and token rotation — and in exchange has no external dependency in its login path and complete freedom over its token shape.

The authorizer contract: what belongs in the context

Whatever verifies the token produces a small, fixed struct. This is the most important interface in the system, because everything downstream trusts it completely:

{
  "org_id":       "…",       # the tenant. non-empty, or the request never got here.
  "principal_id": "…",       # YOUR user id, not the IdP's subject
  "username":     "…",       # for logs and audit rows
  "role":         "manager", # from the database, not the claim
  "scopes":       "a,b,c",   # API Gateway context values are STRINGS
  "auth_type":    "jwt"      # jwt | api_key | internal — audit needs to know
}

Refresh tokens, done properly

Short access tokens are only usable if refreshing is safe. Whether the provider does it or you do, the same four properties apply:

Tenant scoping is not authentication

A verified token tells you the caller is Maria at Acme. It does not stop a handler from returning Beta Corp's shipments. Every system here needed a second, separate layer — and via's is the most explicit about it, deriving both the query filter and the permission rules from one map:

/**
 * SINGLE SOURCE OF TRUTH for row-level tenant scoping.
 * Both the CASL ability factory and the ScopeService derive from this map,
 * so a role's scope is defined in one place and the two cannot drift.
 */
export const SCOPE_BY_ROLE: Record<UserRole, (p: ScopePrincipal) => ScopeFilter | null> = {
  [UserRole.VIA_ADMIN]: () => null,                                      // platform admin: no filter
  [UserRole.COMPANY]:   (p) => ({ column: 'agency_id',   value: p.agencyId! }),
  [UserRole.TERMINAL]:  (p) => ({ column: 'terminal_id', value: p.terminalId! }),
  [UserRole.DRIVER]:    (p) => ({ column: 'operator_id', value: p.userId }),
};

// every list query goes through this — the WHERE clause is not optional
applyScope<T>(qb: SelectQueryBuilder<T>, scope: ScopeContext): SelectQueryBuilder<T> {
  const filter = this.resolveFilter(scope);
  if (!filter) return qb;                       // platform admin only
  return qb.andWhere(`${qb.alias}.${filter.column} = :p`, { p: filter.value });
}

Three ways to enforce it, and the right answer depends on where your trust boundary is:

Five failures that actually happen

Choosing: managed identity or your own