Sessions

List and revoke active sessions on a Global Account

Every call to POST /auth/credentials/{id}/verify creates a new session — an authenticated signing context with a 15-minute lifetime by default. Sessions accumulate: a customer signed in on a laptop and a phone has two active sessions, each with its own session signing key held on that device. Use the session endpoints to show active sign-ins, refresh an active session before it expires, and sign out of a specific device.

List active sessions

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

Response (200):

{
  "data": [
    {
      "id": "Session:019542f5-b3e7-1d02-0000-000000000003",
      "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
      "type": "PASSKEY",
      "nickname": "iPhone Face-ID",
      "createdAt": "2026-04-19T12:00:02Z",
      "updatedAt": "2026-04-19T12:00:02Z",
      "expiresAt": "2026-04-19T12:15:02Z"
    },
    {
      "id": "Session:019542f5-b3e7-1d02-0000-000000000007",
      "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
      "type": "EMAIL_OTP",
      "nickname": "[e-mail]",
      "createdAt": "2026-04-19T10:01:00Z",
      "updatedAt": "2026-04-19T10:01:00Z",
      "expiresAt": "2026-04-19T10:16:00Z"
    }
  ]
}

The list endpoint returns all active sessions; expired sessions are not included. encryptedSessionSigningKey is never returned here — it is delivered exactly once on the verify response and never again.

Refresh a session

Session refresh creates a new session signing key from an existing active session. Use this when the customer is still present and the current session is close to expiration. If the session has already expired, reauthenticate with the original credential instead.

1. First call — receive the challenge

   curl -X POST "$GRID_BASE_URL/auth/sessions/Session:019542f5-b3e7-1d02-0000-000000000003/refresh" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
     }'
   

   Response (202):

   {
     "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"targetPublicKey\":\"04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V2\"}",
     "requestId": "Request:8c1e7f55-7b9c-4383-86c7-0cbde77c7328",
     "expiresAt": "2026-04-19T12:10:00Z"
   }
   
2. Client stamps the payload

   Build a Turnkey API-key stamp over payloadToSign with the current session signing key.

3. Signed retry — receive the refreshed session

   curl -X POST "$GRID_BASE_URL/auth/sessions/Session:019542f5-b3e7-1d02-0000-000000000003/refresh" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -H "Grid-Wallet-Signature: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4iLCJzY2hlbWUiOiJTSUdOQVRVUkVfU0NIRU1FX1RLX0FQSV9QMjU2Iiwic2lnbmF0dXJlIjoiMzA0NTAyMjEwMC4uLiJ9" \
     -H "Request-Id: Request:8c1e7f55-7b9c-4383-86c7-0cbde77c7328" \
     -d '{
       "clientPublicKey": "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
     }'
   

   Response (201): AuthSession with a new encryptedSessionSigningKey. Decrypt it with the private key matching the clientPublicKey above and replace the old session signing key on the client.

Revoke a session

Session revocation uses the same signed-retry pattern as credential management. Unlike credential revocation, a session can revoke itself — this is how self-logout works: sign with the session key you are about to invalidate.

1. First call — receive the challenge

   curl -X DELETE "$GRID_BASE_URL/auth/sessions/Session:019542f5-b3e7-1d02-0000-000000000003" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
   

   Response (202):

   {
     "type": "PASSKEY",
     "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"apiKeyIds\":[\"api_key_2m9F...\"],\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_DELETE_API_KEYS\"}",
     "requestId": "Request:2b1e5a08-9c44-4e91-ae7f-6d0b3f8c1e22",
     "expiresAt": "2026-04-19T12:10:00Z"
   }
   
2. Client stamps the payload

   Build a Turnkey API-key stamp over payloadToSign with any active session signing key on the same account — either the session being revoked (self-logout) or another session (admin-style sign-out of a different device).

3. Signed retry — session is revoked

   curl -X DELETE "$GRID_BASE_URL/auth/sessions/Session:019542f5-b3e7-1d02-0000-000000000003" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Grid-Wallet-Signature: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4iLCJzY2hlbWUiOiJTSUdOQVRVUkVfU0NIRU1FX1RLX0FQSV9QMjU2Iiwic2lnbmF0dXJlIjoiMzA0NTAyMjEwMC4uLiJ9" \
     -H "Request-Id: Request:2b1e5a08-9c44-4e91-ae7f-6d0b3f8c1e22"
   

   Response: 204 No Content.

Revoking a session only invalidates the session signing key, not the credential that issued it. The next call to POST /auth/credentials/{id}/verify on that credential still works and issues a brand new session.