BUSINESS customer’s Global Account can have more than one administrator. Each additional administrator holds their own EMAIL_OTP, PASSKEY, or EVM_WALLET credential, tagged with an adminReference your platform chooses, and signs for the wallet with it as the owner does.
Each administrator credential is a wallet user of its own, apart from the owner’s, so removing one administrator leaves every other credential standing. The wallet stays self-custodial: Grid never adds an administrator on its own. Every add and every removal is approved by a signature from an existing verified credential on the account, either the owner’s or another administrator’s.
Before you add an administrator:
- The customer must be a
BUSINESScustomer. For any other customer,POST /auth/admin-credentialsreturns400 INVALID_INPUT. - The Global Account’s wallet must be created and the account’s
statusmust beACTIVE. While the account has no wallet or is stillPENDING,POST /auth/admin-credentialsreturns409 WALLET_NOT_PROVISIONED. - Someone already on the account, the owner or an existing administrator, needs an active session to approve the add. See Authentication.
The admin reference
adminReference is your platform’s opaque reference for the administrator, such as a member id, from 1 to 255 characters. Grid stores it as given and returns it on the administrator’s credentials and sessions. The owner’s credentials and sessions carry no adminReference.
Grid uses it to remove an administrator: revoking an adminReference revokes every credential that carries it. An administrator added with another administrator’s approval gets their own adminReference and is removed separately.
Add an administrator
Adding an administrator takes two signed steps. The first call returns apayloadToSign that creates the administrator’s wallet user. Its signed retry returns a second payloadToSign that grants that user the authority to sign for the wallet. The second signed retry returns the new credential.
Both signatures come from the session of an existing verified credential on the account. The new administrator takes no part until they sign in.
1
First call — receive the first challenge
The request body depends on the administrator’s credential type.
EMAIL_OTP:emailis the administrator’s own address, which receives their one-time codes. It must differ from every other email credential on the account.PASSKEY: the samenickname,challenge, andattestationfields as a passkey registration. The administrator’s device creates the passkey, and its registration result fills$CREDENTIAL_ID,$CLIENT_DATA_JSON, and$ATTESTATION_OBJECTas base64url, as in the guide’s passkey registration sample. Grid accepts only ES256 (-7) and RS256 (-257) passkeys.EVM_WALLET:publicKeyis the secp256k1 public key of the administrator’s wallet, as0x-prefixed hex: compressed (33 bytes, starting02or03) or uncompressed (65 bytes, starting04). It must be the key of a wallet with a single private key, not a smart-contract account. Grid derives the wallet’s address and returns it as the credential’snickname. The new administrator’s wallet signs nothing to be added: Grid issues no ownership challenge, and the wallet first signs when the administrator signs in.
payloadToSign, requestId, and expiresAt.2
First signed retry — receive the second challenge
The client stamps
payloadToSign with the session signing key of an existing verified credential. Retry the identical request with Grid-Wallet-Signature and Request-Id.Response (202): a second payloadToSign and a new requestId.3
Second signed retry — the administrator is added
Stamp the second
payloadToSign the same way, then retry the identical request again with the new stamp and the second requestId.Response (201):POST /auth/admin-credentials again with the same adminReference.
Administrator sign-in
The administrator signs in withPOST /auth/credentials/{id}/challenge and POST /auth/credentials/{id}/verify, as the owner signs in with a credential of the same type. An EMAIL_OTP administrator’s codes go to their own email address. An EVM_WALLET administrator’s wallet signs the challenge’s payloadToSign and sends it to /verify as signature. See EVM wallet sign-in.
Errors
Grid returns
404 when the internal account does not exist.
List administrators
Administrators’ credentials appear inGET /auth/credentials alongside the owner’s, and their sessions appear in GET /auth/sessions. An administrator’s entries carry their adminReference; the owner’s carry none.
What an administrator’s session can do
An administrator’s session signs for the wallet as the owner’s does, with these differences:- It cannot add credentials with
POST /auth/credentials. Grid refuses an administrator’s signature there with403 FORBIDDEN. A credential added there carries noadminReference, so it would outlive the administrator’s removal. Administrators add their own credentials withPOST /auth/admin-credentials. - It can approve adding or removing another administrator. That administrator gets their own
adminReference. - Its credentials are removed only as a whole administrator.
DELETE /auth/credentials/{id}refuses an administrator’s credential with400 INVALID_INPUT. UseDELETE /auth/admin-credentials/{adminReference}instead.
EMAIL_OTP credential, and they don’t count as the owner’s remaining credential, so the owner still can’t revoke their own last credential while administrators exist.
Remove an administrator
DELETE /auth/admin-credentials/{adminReference} revokes every credential carrying that adminReference on the account, along with their sessions. It is approved like the add: the first call returns 202, and the session of an existing verified credential on the account stamps it.
1
First call — receive the challenge
payloadToSign, requestId, and expiresAt.2
Signed retry — the administrator is removed
204 No Content.400 INVALID_INPUT when it would leave the account with no active credential. It returns 404 when the account has no administrator with that adminReference.