Skip to main content
POST
/
auth
/
verify
Verify OTP
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/auth/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-grid-environment: <api-key>' \
  --data '{
  "email": "user@example.com",
  "otp_code": "123456",
  "kms_provider": "privy",
  "kms_provider_config": {
    "encryption_public_key": "base64encodedkey..."
  }
}'
{
  "data": {
    "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "policies": {
      "signers": [
        {
          "address": "11111111111111111111111111111112",
          "role": "primary",
          "permissions": [
            "CAN_INITIATE",
            "CAN_VOTE"
          ],
          "provider": "privy"
        }
      ],
      "threshold": 1
    },
    "grid_user_id": "123e4567-e89b-12d3-a456-426614174003",
    "authentication": [
      {
        "provider": "privy",
        "session": {
          "user_id": "user123",
          "session": {}
        }
      }
    ]
  },
  "metadata": {
    "request_id": "123e4567-e89b-12d3-a456-426614174001",
    "timestamp": "2023-07-15T14:31:00.000Z"
  }
}
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

API key authentication with Bearer token. Include the API key in the Authorization header as 'Bearer YOUR_API_KEY'

​
x-grid-environment
string
header
required

Environment identifier for the Grid API. Use 'sandbox' for testing on devnet or 'production' for production on mainnet.

Body

application/json
​
email
string<email>
required

Email address used for authentication

​
otp_code
string
required

6-digit OTP code

Required string length: 6
​
kms_provider
enum<string>
required

KMS provider for authentication

Available options:
privy,
passkey,
turnkey,
external
​
kms_provider_config
object
required

Configuration specific to the KMS provider

Response

OTP verified successfully

​
data
object
required

The actual response payload

​
metadata
object
required
⌘I