Skip to content

docs: fix auth account identifiers #476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DhruvPareek wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix auth account identifiers #476

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 13 additions & 16 deletions mintlify/snippets/global-accounts/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ curl -X POST "$GRID_BASE_URL/auth/credentials" \
-H "Content-Type: application/json" \
-d '{
"type": "OAUTH",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"oidcToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9..."
}'
```
Expand Down Expand Up @@ -420,7 +420,7 @@ The lowest-friction credential type — works on any device with email access an

### Email OTP registration

Creating the credential triggers an OTP email to the address you pass. The user reads the code off the email and submits it through your UI.
Creating the credential triggers an OTP email to the customer email on file for the internal account. Do not include an `email` field in the request body; Grid resolves the address from the account's customer record.

```mermaid
sequenceDiagram
Expand All @@ -429,8 +429,8 @@ sequenceDiagram
participant G as Grid
participant E as Email

C->>IB: POST /my-backend/otp/register { email }
IB->>G: POST /auth/credentials { type: EMAIL_OTP, email, accountId }
C->>IB: POST /my-backend/otp/register { accountId }
Copy link
Copy Markdown
Contributor Author

@DhruvPareek DhruvPareek May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe this should just be empty {} ?

IB->>G: POST /auth/credentials { type: EMAIL_OTP, accountId }
G->>E: deliver OTP email
G-->>IB: 201 AuthMethod
IB-->>C: { credentialId }
Expand All @@ -448,8 +448,7 @@ curl -X POST "$GRID_BASE_URL/auth/credentials" \
-H "Content-Type: application/json" \
-d '{
"type": "EMAIL_OTP",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"email": "jane@example.com"
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}'
```

Expand All @@ -458,7 +457,7 @@ curl -X POST "$GRID_BASE_URL/auth/credentials" \
```json
{
"id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000004",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"type": "EMAIL_OTP",
"nickname": "jane@example.com",
"createdAt": "2026-04-19T12:00:00Z",
Expand Down Expand Up @@ -507,7 +506,7 @@ Every Global Account starts with a single credential — the one used in the <a
### List credentials

```bash
curl -X GET "$GRID_BASE_URL/auth/credentials?accountId=EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002" \
curl -X GET "$GRID_BASE_URL/auth/credentials?accountId=InternalAccount:019542f5-b3e7-1d02-0000-000000000002" \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

Expand All @@ -518,15 +517,15 @@ curl -X GET "$GRID_BASE_URL/auth/credentials?accountId=EmbeddedWallet:019542f5-b
"data": [
{
"id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"type": "PASSKEY",
"nickname": "iPhone Face-ID",
"createdAt": "2026-04-08T15:30:01Z",
"updatedAt": "2026-04-08T15:30:01Z"
},
{
"id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000004",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"type": "EMAIL_OTP",
"nickname": "jane@example.com",
"createdAt": "2026-04-09T10:15:00Z",
Expand Down Expand Up @@ -567,7 +566,7 @@ Key rules:

### Add an additional credential

Requires an active session on an *existing* credential on the same account. The first call looks identical to the one used to create the first credential; Grid detects the pre-existing credential and responds `202` instead of `201`.
Requires an active session on an *existing* credential on the same account. The first call looks identical to the one used to create the first credential; Grid detects the pre-existing credential and responds `202` instead of `201`. For `EMAIL_OTP`, Grid uses the customer email on file for the internal account.

<Steps>
<Step title="First call — receive the challenge">
Expand All @@ -577,8 +576,7 @@ Requires an active session on an *existing* credential on the same account. The
-H "Content-Type: application/json" \
-d '{
"type": "EMAIL_OTP",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"email": "jane@example.com"
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}'
```

Expand All @@ -587,7 +585,7 @@ Requires an active session on an *existing* credential on the same account. The
```json
{
"type": "EMAIL_OTP",
"payloadToSign": "{\"requestId\":\"7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002\",\"expiresAt\":\"2026-04-08T15:35:00Z\"}",
"payloadToSign": "{\"requestId\":\"7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21\",\"type\":\"EMAIL_OTP\",\"accountId\":\"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\"expiresAt\":\"2026-04-08T15:35:00Z\"}",
"requestId": "7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
"expiresAt": "2026-04-08T15:35:00Z"
}
Expand All @@ -607,8 +605,7 @@ Requires an active session on an *existing* credential on the same account. The
-H "Request-Id: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
-d '{
"type": "EMAIL_OTP",
"accountId": "EmbeddedWallet:019542f5-b3e7-1d02-0000-000000000002",
"email": "jane@example.com"
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}'
```

Expand Down
Loading