Overview
The API uses Bearer token authentication. You’ll need to:
- Generate a token using your secret key
- Include the token in all subsequent API requests
Generate a Token
Use your secret key to generate an access token for a specific user:
curl -X POST https://api.village.do/v2/auth/tokens \
-H "secret-key: sk_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"external_user_id": "user_123",
"email": "[email protected]"
}'
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"expires_at": "2024-01-07T12:00:00Z"
},
"metadata": {
"request_id": "req_abc123"
}
}
Use the Token
Include the token in all API requests using the Authorization header:
curl https://api.village.do/v2/user/me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Getting Your Secret Key
To get your secret key:
- Log in to the Village Platform Admin
- Navigate to Settings > API Keys
- Create a new API key or copy your existing one
Keep your secret key secure. Only use it server-side to generate tokens. Never
expose it in client-side code.
Demo Credentials
Before integrating with production credentials, you can test the API using demo keys. Demo mode returns real response structures with anonymized data.
| Credential | Value |
|---|
| Secret Key | demo_sk_global |
Example: Generate a Demo Token
curl -X POST https://api.village.do/v2/auth/tokens \
-H "secret-key: demo_sk_global" \
-H "Content-Type: application/json" \
-d '{
"external_user_id": "test_user_123",
"email": "[email protected]"
}'
Demo mode is for testing only. Contact us to get production API keys when
you’re ready to go live.
