Skip to main content
POST
/
auth
/
verify
Verify OTP and complete authentication
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/auth/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "kms_provider": "privy",
  "kms_provider_config": {
    "encryption_public_key": "<string>",
    "otp_id": "<string>"
  },
  "otp_code": "<string>"
}
'
{
  "address": "<string>",
  "authentication": [
    {
      "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": "<unknown>"
          },
          "token": "<string>",
          "user_id": "<string>"
        }
      }
    }
  ],
  "grid_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "policies": {
    "signers": [
      {
        "address": "<string>",
        "permissions": [
          "CAN_INITIATE"
        ],
        "role": "primary",
        "provider": "privy"
      }
    ],
    "threshold": 1,
    "admin_address": "<string>",
    "time_lock": 1
  }
}
This endpoint verifies the OTP received via email for an existing Grid Account and returns authentication credentials for API access.
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 is for authenticating existing Grid Accounts. For new account creation, use the Create Account endpoint followed by account verification.

​
Authentication Flow

  1. Request OTP: Call Initiate Authentication with email address
  2. Generate HPKE Keypair: Create client-side HPKE keys using P-256 curve while waiting for OTP
  3. Verify OTP: Use this endpoint to verify the received OTP code with HPKE public key
  4. Use Credentials: Utilize returned authentication tokens for API access

​
OTP Limits

  • Attempts: Maximum 3 verification attempts per OTP
  • Expiration: 15-minute window from OTP generation
  • Retry: Must request new OTP if limits exceeded

​
Required Configuration

When using Privy as the authentication provider (default), you must include a kms_provider_config with your HPKE public key to receive encrypted authorization keys. This enables secure transaction signing for your Grid Account.

​
Complete Implementation Guide

For comprehensive implementation details including:
  • kms_provider_config creation
  • HPKE keypair generation with P-256 curve and DER formatting
  • Authorization key decryption using ECDH + HKDF + ChaCha20-Poly1305
  • Transaction payload signing with JSON canonicalization
  • Error handling and security best practices
  • Language-agnostic examples
See the Primary Provider Integration guide.

​
Response Data

Upon successful verification, you receive:
  • Authentication tokens for API access
  • Account information including Grid Account address
  • Session credentials for subsequent API calls
The authentication session remains valid until expiration, allowing you to make authenticated requests to Grid API endpoints.

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Body

application/json
​
email
string
required
​
kms_provider
enum<string>
required
Available options:
privy,
dynamic,
passkey,
turnkey,
external
​
kms_provider_config
object
required
​
otp_code
string
required

Response

Authentication successful

​
address
string
required
​
authentication
object[]
required
​
grid_user_id
string<uuid>
required
​
policies
object
required