Authorization

Commerces API uses OAuth 2.0 for secure authorization. Each commerce affiliated with zazpay will receive a dedicated client configuration to access the API.

Prerequisites

Before you can access the commerces API, you will receive an email containing:

• Client ID: Your unique client identifier
• Client Secret: Your client secret for authorization
• Token Endpoint: The authorization server URL

Getting an Access Token

Note: The token endpoint base URL comes from your provisioned KEYCLOAK_AUTH_SERVER_URL. In production it is typically https://auth.server.zazpay.mx. Use the exact value provided for your environment.

Using Client Credentials Flow

The recommended approach for server-to-server communication is the Client Credentials flow:

curl -X POST \
  https://auth.server.zazpay.mx/realms/commerces/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

Response Format

A successful authorization will return:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "your-session-state",
  "scope": "profile email"
}

Using the Access Token

Once you have obtained an access token, include it in the Authorization header of all API requests:

curl -X GET \
  https://api.developer.zazpay.mx/v1/your-endpoint \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Error Handling

Common authorization Errors

HTTP Status	Error Code	Description	Solution
401	invalid_client	Invalid client credentials	Verify your client ID and secret
401	invalid_grant	Invalid or expired refresh token	Request a new access token
400	invalid_request	Missing required parameters	Check request format
403	insufficient_scope	Insufficient permissions	Contact zazpay support

Example Error Response

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Security Best Practices

1. Store credentials securely: Never hardcode client secrets in your source code
2. Use environment variables: Store sensitive data in environment variables
3. Implement token caching: Cache access tokens and refresh them before expiration
4. Monitor token expiration: Set up alerts for token expiration
5. Use HTTPS: Always use HTTPS for all API communications
6. Rotate secrets regularly: Contact zazpay to rotate your client secret periodically

Support

If you encounter any authorization issues or need assistance with your client configuration, please contact zazpay support at hola@zazpay.mx.

Note: Your client credentials will be shared via email. Keep them secure and never share them publicly or commit them to version control systems.