Add an administrator credential

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/auth/admin-credentials \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "EMAIL_OTP",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "adminReference": "member_8f2c1a",
  "email": "admin@example.com"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'EMAIL_OTP',
    accountId: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
    adminReference: 'member_8f2c1a',
    email: 'admin@example.com'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/auth/admin-credentials', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"type\": \"EMAIL_OTP\",\n  \"accountId\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\n  \"adminReference\": \"member_8f2c1a\",\n  \"email\": \"admin@example.com\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/auth/admin-credentials")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "OAUTH",
  "nickname": "example@lightspark.com",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z",
  "credentialId": "KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew",
  "adminReference": "member_8f2c1a",
  "otpEncryptionTargetBundle": "{\"version\":\"v1.0.0\",\"data\":\"7b227461726765745075626c6963...\",\"dataSignature\":\"30450221...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_EXAMPLE\"}",
  "requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
  "expiresAt": "2026-04-08T15:35:00Z",
  "type": "OAUTH"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Embedded Wallet Auth

Add an administrator credential

Add a credential for an additional administrator of a BUSINESS customer’s Embedded Wallet. The new administrator gets their own EMAIL_OTP or PASSKEY credential, tagged with adminReference, and signs for the wallet with it as the owner does. The wallet stays non-custodial: Grid never adds an administrator on its own, and every step is authorised by a signature from an existing verified credential on the account (the owner’s, or another administrator’s).

This is the only way an administrator adds a credential. An administrator’s session cannot sign POST /auth/credentials, which Grid refuses with 403 FORBIDDEN, so every credential belonging to an administrator carries their adminReference and removing them revokes it. An administrator added with another administrator’s signature has their own adminReference and is removed separately.

It takes two signed steps. The first call returns 202 with a payloadToSign that creates the administrator’s wallet user; the signed retry returns another 202 whose payload grants that user the authority to sign for the wallet; the second signed retry returns 201 with the new AuthMethod. The administrator then signs in with POST /auth/credentials/{id}/challenge and POST /auth/credentials/{id}/verify.

POST

auth

admin-credentials

Add an administrator credential

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/auth/admin-credentials \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "EMAIL_OTP",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "adminReference": "member_8f2c1a",
  "email": "admin@example.com"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'EMAIL_OTP',
    accountId: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
    adminReference: 'member_8f2c1a',
    email: 'admin@example.com'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/auth/admin-credentials', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"type\": \"EMAIL_OTP\",\n  \"accountId\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\n  \"adminReference\": \"member_8f2c1a\",\n  \"email\": \"admin@example.com\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/auth/admin-credentials")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "type": "OAUTH",
  "nickname": "example@lightspark.com",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z",
  "credentialId": "KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew",
  "adminReference": "member_8f2c1a",
  "otpEncryptionTargetBundle": "{\"version\":\"v1.0.0\",\"data\":\"7b227461726765745075626c6963...\",\"dataSignature\":\"30450221...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_EXAMPLE\"}",
  "requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
  "expiresAt": "2026-04-08T15:35:00Z",
  "type": "OAUTH"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature

string

Full API-key stamp built over the prior payloadToSign with the session API keypair of an existing verified credential on the same internal account. Required on each signed retry.

Request-Id

string

The requestId of the 202 being answered, echoed back exactly on the signed retry. Must be paired with Grid-Wallet-Signature.

Body

application/json

Email OTP Admin Credential Create Request
Passkey Admin Credential Create Request

type

enum<string>

required

Discriminator value identifying this as an email OTP credential.

Available options:

EMAIL_OTP

accountId

string

required

Identifier of the internal account that this credential will authenticate.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

adminReference

string

required

The platform's opaque reference for the administrator the credential belongs to, such as a member id. Grid stores it as given and uses it to revoke all of the administrator's credentials together.

Required string length: 1 - 255

Example:

"member_8f2c1a"

string<email>

required

The administrator's email address, which receives their one-time codes. Must differ from every other email credential on the account.

Maximum string length: 255

Example:

"admin@example.com"

Response

The administrator's credential was added.

Strict wrapper around AuthMethod. Used directly as the registration response on POST /auth/credentials and inside AuthCredentialResponseOneOf for the EMAIL_OTP / SMS_OTP branches of POST /auth/credentials/{id}/challenge. The only difference from AuthMethod is unevaluatedProperties: false, which disambiguates the oneOf against PasskeyAuthChallenge — without the strictness, an AuthMethod with extra fields would ambiguously match both branches.

For EMAIL_OTP and SMS_OTP credentials, responses that initiate or reissue an OTP challenge carry otpEncryptionTargetBundle so the client can HPKE-encrypt the OTP code in the subsequent POST /auth/credentials/{id}/verify call without the plaintext code ever transiting the server. First-time EMAIL_OTP wallet bootstrap registration can omit it; call POST /auth/credentials/{id}/challenge if it is absent.

string

required

System-generated unique identifier for the authentication credential.

Example:

"AuthMethod:019542f5-b3e7-1d02-0000-000000000001"

accountId

string

required

Identifier of the internal account that this credential authenticates.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

type

enum<string>

required

The type of authentication credential.

OAUTH: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple.
EMAIL_OTP: A one-time password delivered to the user's email address.
SMS_OTP: A one-time password delivered to the user's phone number.
PASSKEY: A WebAuthn passkey bound to the user's device.

Available options:

OAUTH,

EMAIL_OTP,

SMS_OTP,

PASSKEY

nickname

string

required

Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for SMS_OTP credentials this is the E.164 phone number; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time.

Example:

"example@lightspark.com"

createdAt

string<date-time>

required

Creation timestamp.

Example:

"2026-04-08T15:30:01Z"

updatedAt

string<date-time>

required

Last update timestamp.

Example:

"2026-04-08T15:35:00Z"

credentialId

string

Base64url-encoded WebAuthn credential identifier for this passkey. Present only for PASSKEY authentication credentials. Corresponds to PublicKeyCredential.rawId; pass this value as allowCredentials[].id when requesting a passkey assertion for this auth method.

Example:

"KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew"

adminReference

string

The platform's reference for the administrator this credential belongs to, for a credential added with POST /auth/admin-credentials. Absent for the account owner's credentials.

Example:

"member_8f2c1a"

otpEncryptionTargetBundle

string

HPKE encryption target bundle for a freshly initiated OTP challenge. Returned only on EMAIL_OTP and SMS_OTP responses that initiate or reissue an OTP challenge, such as POST /auth/credentials/{id}/challenge and signed-retry add responses. It is omitted from first-time EMAIL_OTP wallet bootstrap registration; call POST /auth/credentials/{id}/challenge for the new credential if it is absent. The client generates an ephemeral P-256 keypair (the Target Encryption Key, or TEK) and uses this bundle as the recipient when HPKE-encrypting {otp_code, public_key}, where public_key is the compressed TEK public key; the encrypted payload is submitted as encryptedOtpBundle on POST /auth/credentials/{id}/verify. The bundle is one-time-use per OTP issuance — re-issue via POST /auth/credentials/{id}/challenge to obtain a fresh bundle. The matching TEK private key must remain on the client and is used to stamp the exact UTF-8 bytes of the payloadToSign string returned by the first verify call. Preserve that string unchanged on the signed retry. Treat the bundle as opaque and pass it to your HPKE library; the Global Accounts client-keys guide shows how.

Example:

"{\"version\":\"v1.0.0\",\"data\":\"7b227461726765745075626c6963...\",\"dataSignature\":\"30450221...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"

Using the API

API documentation

Add an administrator credential

Authorizations

Headers

Body

Response