A single internal account can hold one
EMAIL_OTP credential, one SMS_OTP credential, and multiple distinct PASSKEY and EVM_WALLET credentials concurrently. OAUTH credentials can be added for each supported provider identity.
When the wallet is created
When a Global Account’s wallet is created depends on your platform’sembeddedWalletConfig.walletProvisioning, set with PATCH /config. Grid reads it once, when the customer’s first Global Account opens.
AT_CUSTOMER_CREATE(default): Grid creates the wallet when the customer’s Global Account opens, with anEMAIL_OTPcredential tied to the customer email on file. Use that credential to mint the first session. See Default Email OTP credential. A customer with no email on file when the account opens gets theAT_FIRST_CREDENTIALbehavior.AT_FIRST_CREDENTIAL: the Global Account is created asPENDING, with no wallet and no credentials. The first credential you add withPOST /auth/credentialscreates the wallet, with that credential as its only one. It needs no signature and returns201. It can beEMAIL_OTP,OAUTH,PASSKEY, orEVM_WALLET. AnEMAIL_OTPfirst credential uses the customer email on file.SMS_OTPcannot be first and returns409 WALLET_NOT_PROVISIONED.
POST /auth/credentials returns 409 WALLET_NOT_PROVISIONED. Retry once the account’s status is ACTIVE. Activate the first credential the same way you would any new credential of its type, as described below. An EVM_WALLET first credential also proves control of the wallet first. See EVM wallet registration.
Registration vs. verification
Use the account’s first credential to mint the first session, or use anOAUTH, PASSKEY, or EVM_WALLET credential after you add one.
To produce a session:
EMAIL_OTP— if you need a fresh OTP or encryption target, first callPOST /auth/credentials/{id}/challenge. Generate a P-256 client key pair, HPKE-encrypt the OTP value plus the public key intoencryptedOtpBundle, then callPOST /auth/credentials/{id}/verify. Grid returns a202signed-retry challenge; stamp itspayloadToSignwith the same private key and retry withGrid-Wallet-SignatureplusRequest-Id. The signed retry returns the session; the private key you generated is the session signing key.OAUTH— callPOST /auth/credentials/{id}/verifywith a fresh OIDC token plusclientPublicKey. The response is the session; the private key matchingclientPublicKeyis the session signing key.PASSKEY— callPOST /auth/credentials/{id}/challengewith yourclientPublicKeyto receive a Grid-issuedchallengeandrequestId, UTF-8 encode the challenge string fornavigator.credentials.get(), then callPOST /auth/credentials/{id}/verifywith the resulting assertion and theRequest-Idheader. Grid bakes theclientPublicKeyfrom the/challengecall into the session-creation payload, so it does not appear on the/verifybody.EVM_WALLET— callPOST /auth/credentials/{id}/challengewith yourclientPublicKeyto receive apayloadToSignandrequestId. Have the wallet signpayloadToSignwithpersonal_sign, then callPOST /auth/credentials/{id}/verifywith thesignatureand theRequest-Idheader. The response is the session; the private key matchingclientPublicKeyis the session signing key.
POST /auth/credentials with the new credential details. Because the account already has a credential, Grid returns a 202 signed-retry challenge. Stamp that payloadToSign with an active session signing key, then retry the same request with Grid-Wallet-Signature and Request-Id. The signed retry returns the new AuthMethod.
Re-authentication after a session expires skips the original POST /auth/credentials create call but otherwise follows the same per-type pattern. EMAIL_OTP re-auth needs a fresh OTP email, so call POST /auth/credentials/{id}/challenge first; PASSKEY and EVM_WALLET re-auth use the same /challenge (with clientPublicKey) → /verify two-step as the first authentication; OAUTH is the exception — since proof of control is a fresh OIDC token, there’s nothing to pre-issue, so /verify alone suffices.
Passkey
Passkey registration
Passkey registration spans four parties: the client (browser or app), your integrator backend, Grid, and the platform authenticator (Touch ID / Face ID / Windows Hello / a security key). Your backend issues the WebAuthn registration challenge. Registering the passkey on Grid is an additional-credential signed-retry flow, authorized by an active session from an existing credential. The first authentication challenge is requested explicitly viaPOST /auth/credentials/{id}/challenge — same call shape used for every subsequent reauthentication.
The challenge on POST /auth/credentials is the one your backend issued for WebAuthn registration. The signed-retry payloadToSign is the registration payload that the customer’s current session authorizes. The challenge used for the WebAuthn assertion comes later from POST /auth/credentials/{id}/challenge — Grid bakes the clientPublicKey you send there into the session-creation payload, so the resulting session belongs to the key the device generated. Because that key plumbing happens on /challenge, the subsequent /verify call carries only the assertion (plus the Request-Id header).
Client sample code
The client never talks to Grid. It talks to your integrator backend — the snippets below simulate that call withfetch('/my-backend/...'), which your backend then relays to Grid.
Grid accepts only ES256 (-7) and RS256 (-257) passkeys, so request both in pubKeyCredParams with ES256 first.
WebAuthn → Grid parameter map
These are the fields you need to pass through on each hop. Registration (/auth/credentials):
Authentication challenge (
/auth/credentials/{id}/challenge):
Assertion (
/auth/credentials/{id}/verify):
The WebAuthn spec names the field
clientDataJSON. Grid spells it clientDataJson (lowercase json) for consistency with the rest of the API. The bytes are identical — only the field name changes.Passkey reauthentication
When a session expires the client re-verifies without recreating the credential. Reauthentication uses the same/challenge → /verify shape as the first authentication: generate a fresh client key pair, call POST /auth/credentials/{id}/challenge with the new clientPublicKey, UTF-8 encode the returned challenge string for navigator.credentials.get(), then call /verify with the assertion and the matching Request-Id header.
OAuth (OIDC)
Use an OAuth credential when your platform already authenticates the user with an OpenID Connect identity provider (Google, Apple, your own IdP) and you want Grid to trust that same identity. Adding OAuth to an initialized Global Account requires an active session from an existing credential and uses the same signed-retry pattern as passkey registration.OAuth registration
Grid validates the OIDC token signature against the issuer’s JWKS on every call and requiresiat to be no more than 60 seconds older than the request. Use a fresh token for each verify call; cached tokens will fail. The token identity (iss, aud, and sub) must match the OAuth credential being verified.
In sandbox, OAuth still uses JWT-shaped OIDC tokens. The sandbox skips real IdP signature verification, but it validates the same identity and freshness claims. For
verify, include nonce equal to the lowercase hex SHA-256 digest of the clientPublicKey string exactly as sent: the compressed key in lowercase hex. See Sandbox testing.201 AuthMethod with nickname populated from the OIDC token’s email claim.
OAuth verify / reauthentication
POST /auth/credentials/{id}/verify is also the reauthentication path — call it with a fresh OIDC token whenever the session expires.
Email OTP
The lowest-friction credential type — works on any device with email access and requires no biometric hardware, identity provider, or client-side setup beyond an input field for the code. Under the defaultAT_CUSTOMER_CREATE wallet provisioning, Grid creates the account’s EMAIL_OTP credential with the wallet. Call POST /auth/credentials for EMAIL_OTP when it is the first credential under AT_FIRST_CREDENTIAL, or to add it back after it was removed.
Default Email OTP credential
UnderAT_CUSTOMER_CREATE (the default), Grid creates the first EMAIL_OTP credential when it creates the wallet. Under AT_FIRST_CREDENTIAL, there is no default credential: the first credential you add creates the wallet. See When the wallet is created. The credential uses the customer email on file for the internal account. To authenticate with it, send an OTP challenge, then verify using the secure encrypted OTP flow.
The client never sends the plaintext OTP code. Instead, it HPKE-encrypts the code (together with a fresh public key) to an enclave bundle returned from the challenge. The server is a pass-through and never sees the plaintext.
{otp_code, public_key} under otpEncryptionTargetBundle, and submits the encrypted payload. public_key must be the compressed public key (02 or 03 prefix). See Encrypt the OTP code for implementation details.
Then verify with the encrypted OTP bundle:
payloadToSign, unchanged, with the TEK private key (the same key whose public key was encrypted in the bundle), then retries the same request body with the stamp:
verify shares its terminal status code with the still-processing response: a 200 here is only a session if the body isn’t { "status": "PROCESSING" }. See handling a still-processing response — if you get PROCESSING, re-send the identical signed retry (same encryptedOtpBundle, Grid-Wallet-Signature, and Request-Id) until you get the session shown above.
In sandbox, the OTP code is always
000000 — encrypt that value in the bundle. The sandbox runs real HPKE end-to-end; the only shortcut is skipping email delivery. See Client keys for the encryption flow.Resending an OTP
If the code expires or the email didn’t arrive, re-issue the challenge withPOST /auth/credentials/{id}/challenge. This sends a fresh OTP email and leaves the AuthMethod otherwise untouched. challenge can also return a still-processing 200 while the resend settles at the wallet provider — re-request the challenge until you get the AuthMethod back rather than a fresh OTP being sent twice.
Email OTP reauthentication
Same pattern as the first activation: call/challenge to send a new OTP and receive a fresh otpEncryptionTargetBundle, generate a new TEK key pair, build the encryptedOtpBundle, and complete the two-step verify flow.
Changing the sign-in email or phone number
TheEMAIL_OTP address is the customer email on file, and the SMS_OTP number is the customer phone number. The customer must prove they control a new address or number before it replaces the one they sign in with. Changing it takes four calls, and the same steps apply to phoneNumber with SMS_OTP.
1
Register the new address
Call
POST /auth/credentials with the new address. Grid sends a code to it and returns the replacement credential with an otpEncryptionTargetBundle. The current credential keeps working until the change lands.2
Verify the code
Encrypt the code the customer received to that
otpEncryptionTargetBundle, as for a login, and send it to POST /auth/credentials/{id}/verify with the replacement’s id. Grid answers 204 with no session. A replacement that is not verified within 24 hours expires.3
Update the customer
Call
PATCH /customers/{customerId} with only customerType and the new address. Grid answers 202 with payloadToSign, requestId, and expiresAt. Make this call soon after verifying. If the verification would lapse before the challenge does, Grid returns 400 AUTH_CREDENTIAL_VERIFICATION_EXPIRED, and the customer must verify again.4
Signed retry
The client stamps
payloadToSign with an active session signing key on the same account. Retry the identical request with Grid-Wallet-Signature and Request-Id. Grid answers 200 with the updated customer, and the new address becomes the account’s EMAIL_OTP credential in place of the old one. A 200 with { "status": "PROCESSING" } means the change is still landing: re-send the identical signed request until it returns the customer.PATCH that changes the sign-in address without a verified replacement returns 400 AUTH_CREDENTIAL_VERIFICATION_REQUIRED. The change must be sent on its own, so a request that also changes other customer fields returns 400 INVALID_INPUT. Customers without an EMAIL_OTP or SMS_OTP credential of that type change email or phoneNumber with a plain update.
EVM wallet
Use anEVM_WALLET credential when the user already holds an Ethereum or other EVM wallet and you want that wallet to sign them in. The wallet proves control by signing Grid’s messages with personal_sign (EIP-191). The signature names no chain, so the same key and 0x address work on any EVM chain, such as Ethereum, Base, Polygon, or Arbitrum. The credential’s nickname is the wallet’s address.
The wallet must be an externally owned account: a wallet with a single private key. Smart-contract wallets that sign through ERC-1271, such as ERC-4337 accounts, are not supported. They have no single key whose signature recovers to their address, so registering one returns 401. If your users hold a smart-contract account, register the externally owned account that owns it.
The wallet signs only to prove control and to open sessions. After sign-in, the client signs account actions with its session signing key, as with every other credential type.
EVM wallet registration
EveryEVM_WALLET registration starts with an ownership challenge. Call POST /auth/credentials with the wallet’s address. Grid answers 202 with a payloadToSign message it writes and a requestId:
appName and names the address, the account, a random nonce, and when it was issued and expires. The challenge expires 5 minutes after it is issued. The client constructs nothing: the wallet signs the message exactly as returned. Retry the same request with the signature as the Grid-Wallet-Ownership-Signature header and the requestId as Request-Id.
As the account’s first credential
If the account has no wallet yet, as underAT_FIRST_CREDENTIAL (see When the wallet is created), the ownership retry creates it, with this EVM wallet as its only credential, and returns 201 with the AuthMethod. No session signature is needed, because there is no existing credential to sign with.
On an account that already has a wallet
Adding an EVM wallet to an existing wallet takes three calls. The wallet proves control, then an active session on an existing credential approves the add.- Ownership challenge.
POST /auth/credentialsreturns the first202, as shown above. - Ownership proof. The retry with
Grid-Wallet-Ownership-Signaturereturns a second202with a newpayloadToSignandrequestId. - Approval. Stamp the second
payloadToSignwith the session signing key of an active session on an existing credential, then retry the same request withGrid-Wallet-Signatureand the secondrequestIdasRequest-Id. Grid returns201with theAuthMethod. This retry can return a still-processing200; re-send it until you get the201.
202 expires 5 minutes after it is issued. An administrator’s session cannot approve the add (403 FORBIDDEN). The same EVM wallet can be a credential on more than one internal account.
EVM wallet sign-in
Signing in follows the same/challenge → /verify shape as a passkey, with the wallet’s signature in place of the WebAuthn assertion. Use it for the first session after registration and to reauthenticate after a session expires.
EvmWalletAuthChallenge, which is the credential’s fields plus payloadToSign, requestId, and expiresAt. Here payloadToSign is the session request that registers your clientPublicKey as the session key. The wallet signs it as given, without parsing, re-serializing, or trimming it.
AuthSession. The private key matching clientPublicKey is now the session signing key. signature is the 0x-prefixed 65-byte personal_sign result (r, s and v), as wallets return it.
Client sample code
The client talks to your integrator backend, never to Grid. This sample uses viem with a browser wallet.generateClientKeyPair() and buildGridWalletSignature() are the helpers from Client keys. The approval and /verify calls can return 200 { status: "PROCESSING" }. sendUntilSettled() re-sends the identical request with backoff until Grid returns the result. See Handling a still-processing response.
Web (TypeScript)
In sandbox,
EVM_WALLET has no magic signature. The sandbox verifies the personal_sign signature as production does, so sign with any test key. See Sandbox testing.Revoke an EVM wallet credential
Revoke anEVM_WALLET credential with DELETE /auth/credentials/{id}, like any other credential. Sessions the wallet already opened stay valid until they expire. See Revoke a credential.
EVM wallet errors
Managing credentials
Under the defaultAT_CUSTOMER_CREATE wallet provisioning, every Global Account starts with a single EMAIL_OTP credential — the one used in the quickstart. Under AT_FIRST_CREDENTIAL, it starts with the first credential you add. In production, encourage customers to register a backup credential, such as a passkey or OAuth credential, so the account is recoverable if their primary device is lost. Adding, revoking, and rotating credentials after the first all go through the same two-step signed-retry pattern.
List credentials
The signed-retry pattern
Adding an additional credential, revoking a credential, refreshing or revoking a session, exporting a wallet, updating wallet privacy, and changing a sign-in email or phone number all share the same shape: Key rules:- Always stamp the
payloadToSignbyte-for-byte as Grid returned it. Do not re-parse, re-serialize, or modify whitespace. - Sign with the session private key held on the client — never ship it back to your backend.
- The retry must reach Grid before
expiresAt(typically 5 minutes from issue). - The
requestIdis returned asRequest:<uuid>and is single-use; reusing one yields401.
Handling a still-processing response
The signed retry can come back200 with a WalletOperationProcessing body instead of the terminal success shown above:
To handle it:
- Re-send the exact same signed request — identical body,
Grid-Wallet-Signature, andRequest-Id. Don’t regenerate the stamp or start a fresh request; Grid correlates the retry with the same underlying operation and returns its real outcome once the provider settles, rather than starting a second one. - Show a pending state in your UI while you retry — “removing…” for a credential revoke, “signing in…” for a login — instead of treating
PROCESSINGas an error or leaving the caller blocked with no feedback. - Keep retrying with backoff until you get a terminal response — the success code above, or an error. Grid also reconciles the operation to its terminal state on its own, so even a client that stops retrying and checks back later (for example via
GET /auth/credentialsorGET /auth/sessions) will see the settled result. Wallet export is the exception: Grid never stores the encrypted credentials, so re-sending the signed retry is the only way to receive them. Grid’s own reconciliation settles the operation but has nothing to hand back, and the export challenge expires like any other (typically 5 minutes) — if it lapses, start a fresh export.
verify, challenge, export, and the customer update already use 200 for their terminal success body (AuthSession, the challenge response, the encrypted credentials, or the customer). For those four, 200 alone doesn’t tell you which case you’re in — check the response body’s status field for "PROCESSING" to distinguish it from a settled success. The other four endpoints (add credential, session refresh, revoke credential, revoke session) use 201 or 204 on success, so a 200 by itself already means still-processing.Add an additional credential
Requires an active session on an existing credential on the same account. The first call uses the normal credential-create body; Grid detects the pre-existing credential and responds202 instead of 201. OAUTH, PASSKEY, and EVM_WALLET are the typical additional credential types. An EVM_WALLET credential first proves control of the wallet with an ownership challenge, so it takes one more call than the steps below. See EVM wallet registration. EMAIL_OTP can be added back only after the existing email OTP credential has been removed, because each account supports one.
1
First call — receive the challenge
2
Client stamps the payload
Send
payloadToSign to the client. The client builds a Grid wallet signature with the session signing key from the existing credential’s active session — see signing payloads.3
Signed retry — credential is created
Re-run the same request with the stamp and request id in headers:Response (201): a plain
AuthMethod. If the underlying wallet-provider activity is still settling, this returns 200 { status: "PROCESSING" } instead — see handling a still-processing response; re-send the identical signed request until you get the 201.4
Activate the new credential
Activate the new credential the same way you would activate the first credential of that type —
OAUTH goes straight to POST /auth/credentials/{id}/verify with a fresh clientPublicKey; EMAIL_OTP uses the otpEncryptionTargetBundle from the signed-retry registration response when present, or first calls POST /auth/credentials/{id}/challenge if the bundle is absent; PASSKEY first calls POST /auth/credentials/{id}/challenge with the clientPublicKey to get a Grid-issued WebAuthn challenge, then POST /auth/credentials/{id}/verify with the assertion and the Request-Id header; EVM_WALLET calls the same /challenge with the clientPublicKey, then /verify with the wallet’s signature and the Request-Id header.The account holder may have one
EMAIL_OTP credential per internal account; an administrator’s credentials, added with POST /auth/admin-credentials, are not counted. An administrator’s session cannot add credentials with POST /auth/credentials (403 FORBIDDEN); administrators add their own with POST /auth/admin-credentials. See Administrators. Multiple distinct PASSKEY credentials are allowed; registering the same WebAuthn credentialId twice returns 400 PASSKEY_CREDENTIAL_ALREADY_EXISTS. Multiple distinct EVM_WALLET credentials are allowed too; registering a wallet already on the account returns 400 WALLET_CREDENTIAL_ALREADY_EXISTS.Revoke a credential
A credential is revoked by signing with a session from a different credential on the same account. This prevents a compromised credential from revoking itself to lock the legitimate owner out. An account must keep at least one credential — if only one exists, the revoke call returns400.
1
First call — receive the challenge
2
Client stamps with a different credential's session
The client stamps
payloadToSign with the session signing key of an active session on any other credential (not the one being revoked).3
Signed retry — credential is revoked
204 No Content. Sessions the revoked credential already opened stay valid until they expire. To end one now, revoke it with DELETE /auth/sessions/{id}. See Revoke a session. If the revocation is still settling at the wallet provider, this returns 200 { status: "PROCESSING" } instead — re-send the identical DELETE until you get the 204, and show the credential as “removing…” in your UI in the meantime rather than assuming success or failure.