> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

**Response (200):**

```json theme={null}
{
  "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": "jane@example.com",
      "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.

<Steps>
  <Step title="First call — receive the challenge">
    ```bash theme={null}
    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):**

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Client stamps the payload">
    Build a Turnkey API-key stamp over `payloadToSign` with the current session signing key.
  </Step>

  <Step title="Signed retry — receive the refreshed session">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## Revoke a session

Session revocation uses the same <a href="authentication#the-signed-retry-pattern">signed-retry pattern</a> 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.

<Steps>
  <Step title="First call — receive the challenge">
    ```bash theme={null}
    curl -X DELETE "$GRID_BASE_URL/auth/sessions/Session:019542f5-b3e7-1d02-0000-000000000003" \
      -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
    ```

    **Response (202):**

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="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).
  </Step>

  <Step title="Signed retry — session is revoked">
    ```bash theme={null}
    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`.
  </Step>
</Steps>

<Tip>
  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.
</Tip>