Agent identity
Sign in with the inbox your agent controls.
The agent mints a token for your audience and sends it to you. Markdown: /docs/sign-in-with-cooper.md · API section.
The agent mints a token, then you check it
Sign in with a Cooper inbox is three steps. The agent calls POST /api/v1/inboxes/{inbox_id}/identity-token with the audience you published. It sends that token to you. You check it with POST /api/v1/identity/verify, or you check the signature yourself with the public keys at /.well-known/jwks.json.
The token is a JWT. token_type is agent_identity+jwt. iss is https://cooperemail.com. sub is the inbox id. email is the inbox address, lowercased, and email_verified is true. aud is the audience the agent asked for, compared exactly. ttl_seconds defaults to 300 and must be an integer from 60 to 3600. Minting is limited to 60 tokens an hour per inbox.
cooper.agent is true. cooper.inbox_created_at is when the inbox was created. cooper.custom_domain is true when the address is not on cooperemail.com. cooper.owner_verified is true when a human owner of that inbox is verified. The token does not include an account id, a plan, an API key, or the owner's email or name.
Verify on Cooper, or with the JWKS
POST /api/v1/identity/verify needs no API key. Body is {token, audience, consume?}. audience is required and must be the same string the agent used. consume true stores the jti so a second check returns valid false and error token_already_used. A bad signature, the wrong audience, an expired token, an unknown kid, a deleted inbox, or a suspended account is HTTP 200 with valid false and an error code. A body that is not JSON, or that omits token or audience, is HTTP 400.
The check allows 30 seconds of clock skew on exp and nbf. It looks up the inbox and the account with one indexed query. Verification is limited to 120 requests a minute per IP.
Offline verification with the JWKS cannot see revocation or single-use. It cannot see that the inbox was deleted or the account was suspended after the token was minted. Use POST /api/v1/identity/verify when that matters. consume true is what makes a token single-use.
curl -s https://cooperemail.com/api/v1/identity/verify \
-H "content-type: application/json" \
-d "{\"token\":\"$TOKEN\",\"audience\":\"https://your-service.example\",\"consume\":true}"Check the signature in Node with jose
Install jose in your service. createRemoteJWKSet caches the keys from /.well-known/jwks.json. Pass your audience. This sample checks the signature, iss, aud, and exp. It does not know about single-use or whether the inbox still exists.
import { createRemoteJWKSet, jwtVerify } from "jose";
const JWKS = createRemoteJWKSet(new URL("https://cooperemail.com/.well-known/jwks.json"));
const { payload } = await jwtVerify(token, JWKS, {
issuer: "https://cooperemail.com",
audience: "https://your-service.example",
clockTolerance: 30,
});Audience, lifetime, and what is not in the token
Bind every token to your own audience. An https origin such as https://your-service.example, or another absolute URI of at most 255 characters, is the audience. A token minted for someone else fails aud. Keep the lifetime short. 300 seconds is the default. Pass consume true when a login should work once.
Do not expect an account id, a plan name, an API key, or the owner's email or name. owner_verified is only a boolean. If signing is not configured, the identity routes return HTTP 503 identity_unavailable and every other Cooper route is unchanged.
Discovery: https://cooperemail.com/.well-known/cooper-identity.json and https://cooperemail.com/.well-known/jwks.json. The JWKS response uses Cache-Control: max-age=300.