Skip to main content
POST
/
api
/
grid
/
v1
/
auth
/
refresh-session
cURL
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/auth/refresh-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "encryption_public_key": "<string>",
  "kms_payload": {
    "provider": "privy",
    "session": {
      "Privy": {
        "privy_access_token": "<string>",
        "refresh_token": "<string>",
        "session": {
          "expires_at": 1,
          "wallets": [
            {
              "additional_signers": [
                {
                  "signer_id": "<string>",
                  "override_policy_ids": [
                    "<string>"
                  ]
                }
              ],
              "address": "<string>",
              "chain_type": "solana",
              "created_at": 1,
              "id": "<string>",
              "policy_ids": [
                "<string>"
              ],
              "exported_at": 1,
              "imported_at": 1,
              "owner_id": "<string>",
              "public_key": "<string>"
            }
          ],
          "authorization_key": "<string>",
          "encrypted_authorization_key": {
            "ciphertext": "<string>",
            "encapsulated_key": "<string>",
            "encryption_type": "<string>"
          }
        },
        "token": "<string>",
        "user_id": "<string>"
      }
    }
  }
}
'
{
  "data": {
    "kms_payload": {
      "provider": "privy",
      "session": {
        "Privy": {
          "privy_access_token": "<string>",
          "refresh_token": "<string>",
          "session": {
            "expires_at": 1,
            "wallets": [
              {
                "additional_signers": [
                  {
                    "signer_id": "<string>",
                    "override_policy_ids": [
                      "<string>"
                    ]
                  }
                ],
                "address": "<string>",
                "chain_type": "solana",
                "created_at": 1,
                "id": "<string>",
                "policy_ids": [
                  "<string>"
                ],
                "exported_at": 1,
                "imported_at": 1,
                "owner_id": "<string>",
                "public_key": "<string>"
              }
            ],
            "authorization_key": "<string>",
            "encrypted_authorization_key": {
              "ciphertext": "<string>",
              "encapsulated_key": "<string>",
              "encryption_type": "<string>"
            }
          },
          "token": "<string>",
          "user_id": "<string>"
        }
      }
    }
  },
  "metadata": {
    "request_id": "<string>",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.squads.so/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint refreshes expired authentication sessions for Grid Accounts and returns new encrypted credentials. It implements a two-tier approach to handle different expiration scenarios automatically.
Using the Grid API directly requires advanced configurations. Grid SDK is the recommended way to authenticate accounts. It handles authentication, key management, automatic failover, and transaction signing. Learn more about the Grid SDK in the Grid SDK guide.
This endpoint requires an active bearer token from a previous authentication. For initial authentication, use Initiate Authentication followed by Verify OTP.

​
How Session Refresh Works

Grid automatically handles different token expiration states:
1

Case 1: Re-authentication

If the user token is still valid but the session needs refreshing, the endpoint re-authenticates using the existing token to obtain new encrypted credentials.
2

Case 2: Token Refresh

If the user token has expired, the endpoint uses the refresh token to obtain a new user token, then re-authenticates to get new encrypted credentials.

​
When to Use This Endpoint

Use this endpoint when:
  • Session credentials expire: Your authentication session has expired and you need new credentials
  • Token rotation: Implementing proactive token rotation for enhanced security
  • Long-running applications: Maintaining continuous access without requiring user re-authentication
Automatic Handling The endpoint automatically determines which case of refresh to use based on the token expiration state. You don’t need to specify which approach to use.

​
Required Configuration

You must provide:
  1. kms_payload: Contains the current session information including tokens
  2. encryption_public_key: Your HPKE public key for encrypting new credentials
The endpoint returns new encrypted credentials that can be decrypted using your private key.

​
Complete Implementation Guide

For comprehensive implementation details including:
  • HPKE keypair generation with P-256 curve and DER formatting
  • Encryption public key creation
  • Authorization key decryption using ECDH + HKDF + ChaCha20-Poly1305
  • Session management and token handling
  • Error handling and retry strategies
See the Primary Provider Integration guide.

​
Response Data

Upon successful refresh, you receive:
  • New session credentials: Encrypted with your public key
  • Updated tokens: Fresh user token, access token, and refresh token
  • Provider information: Current KMS provider details
The refreshed session remains valid until expiration, allowing you to continue making authenticated requests to Grid API endpoints.

​
Supported Providers

Currently supported KMS providers:
  • Privy: Full support for two-tier session refresh
  • Turnkey: Coming soon

​
Error Handling

Common error scenarios:
  • 400 Bad Request: Invalid encryption public key or malformed payload
  • 401 Unauthorized: Refresh token expired or invalid, user must re-authenticate
  • 500 Internal Server Error: Service error, retry with exponential backoff

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Body

application/json
​
encryption_public_key
string
required

HPKE public key for encryption

​
kms_payload
object

KMS provider payload (optional - if not provided, will use HTTP-only cookie)

Response

Session refreshed successfully

​
data
object
required
​
metadata
object
required