Skip to main content
Before creating intents, you must create a customer record. This associates your user with Gnosis Ramp and returns an access token for customer-scoped API calls.

​
Create Customer Request

curl -X POST https://api.ramp.gnosis.io/v1/customers \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user-12345"
  }'

​
Request Body

FieldTypeRequiredDescription
idstringYesYour internal user identifier. Use a stable ID from your system.
metadataobjectNoOptional metadata to store with the customer.
Use your internal user ID (e.g., database primary key, auth provider ID) as the customer id. This makes it easy to correlate Gnosis Ramp customers with your users.

​
Response

{
  "id": "user-12345",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "createdAt": "2026-03-29T10:00:00.000Z",
  "updatedAt": "2026-03-29T10:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789"
}

​
Response Fields

FieldDescription
idThe customer ID you provided
accessTokenJWT token for customer-scoped API calls (1 hour validity)
createdAtWhen the customer was created
updatedAtWhen the customer was last updated

​
Using the Access Token

The accessToken is used for all customer-scoped endpoints: 
# Create an intent
curl -X POST https://api.ramp.gnosis.io/v1/intent \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{...}'

# Get customer's intents
curl https://api.ramp.gnosis.io/v1/intent \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

​
Idempotency

Creating a customer with the same id is idempotent — it returns the existing customer with a fresh access token. This is useful for:
  • Refreshing expired tokens
  • Ensuring customers exist before operations
# Call again with same ID - returns existing customer with new token
curl -X POST https://api.ramp.gnosis.io/v1/customers \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"id": "user-12345"}'

​
JavaScript Example

async function createCustomer(userId) {
  const credentials = btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

  const response = await fetch('https://api.ramp.gnosis.io/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ id: userId })
  });

  if (!response.ok) {
    throw new Error(`Failed to create customer: ${response.status}`);
  }

  const customer = await response.json();
  return customer.accessToken;
}

// Usage
const accessToken = await createCustomer('user-12345');

​
Next Steps

External Auth (SIWE)

Enable KYC sharing with Gnosispay wallet authentication.

Create an Intent

Start a ramp operation for the customer.