Authentication Overview

🔑 Authentication Overview

The DogPay's API uses Bearer Token authentication based on the OAuth 2.0 Client Credentials flow. To interact with protected endpoints, you must include a valid access token in your HTTP headers.

1. Generate an Access Token

To get started, you need to exchange your appid and secret for an access_token.

• Endpoint: POST /open-api/v1/auth/access_token
• Grant Type: Must be set to client_credential

# Example Request
curl -X POST "https://prod.wavepool.global/open-api/v1/auth/access_token" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "client_credential",
           "appid": "your_app_id",
           "secret": "your_app_secret"
         }'

2. Using the Token

Include the token in the Authorization header for all subsequent requests:

⏳ Token Lifecycle & Expiration

Understanding how to manage your token is crucial for building a stable integration.

Validity Period

Tokens are valid for 2 hours (7200 seconds) from the moment they are issued. The exact expiration time is returned in the expires_in field of the auth response.

How to Handle Expiration

This API does not use refresh tokens. Once a token expires, it becomes invalid and you must repeat the Step 1 process to obtain a new one.

💡 Best Practices for Token Management

• Cache your Token: Store the token in your application's memory or a secure cache. Do not request a new token for every single API call, as this may lead to rate limiting.

• Proactive Refresh: We recommend re-fetching a new token roughly 5–10 minutes before the current one expires to ensure zero-downtime for your service.

• Error Handling: If your API call returns a 401 Unauthorized error, your application should be programmed to automatically trigger the token acquisition logic and retry the request.

⚠️ Common Issues

• Expired Token: If you use a token older than 2 hours, you will receive a 401 Unauthorized response.
• Missing Bearer Prefix: Ensure your header looks like Bearer eyJhbG... (with the space), not just the token string.
• AppSecret Security: Never hardcode your secret in client-side applications (mobile apps or browsers). Always perform the token exchange on your backend server.