Skip to main content
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

Response (200):
The list endpoint returns all active sessions; expired sessions are not included. Session responses never carry the session signing key. The client generated it and already holds it.

​
Refresh a session

Session refresh issues a new session for a new session signing key, authorized by an existing active session. Generate a fresh client key pair and send its compressed public key in lowercase hex as clientPublicKey (see Generate a client key pair). 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. Refresh uses the same signed-retry pattern as credential management, including the possibility of a still-processing 200 response on the signed retry — re-send the same request until you get the 201 below.
1

First call — receive the challenge

Response (202):
2

Client stamps the payload

Build a Grid wallet signature over payloadToSign with the current session signing key.
3

Signed retry — receive the refreshed session

Response (201): the new AuthSession. The private key matching the clientPublicKey above is now the session signing key, so replace the old one on the client.

​
Revoke a session

Session revocation uses the same signed-retry pattern as credential management, including a possible still-processing 200 response on the signed retry. 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

Response (202):
2

Client stamps the payload

Build a Grid wallet signature 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

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.