OAuth2 Authentication
How to obtain and use access tokens to consume the Nuvy API
ⓘ
Overview
▼
The Nuvy API uses OAuth2 with the Client Credentials flow for authentication. Your application exchanges its credentials (client_id and client_secret) for a time-limited access token, which is then included in every API request.
Your App
→ credentials →
Nuvy OAuth2
→ token →
Your App
→ Bearer →
Nuvy API
1
Obtain Your Credentials
▼
Nuvy will provide you with a pair of credentials:
| Parameter | Description |
|---|---|
| client_id | Your application's unique identifier |
| client_secret | Your application's secret key |
Never expose your client_secret in client-side code, public repositories, or logs. Treat it like a password.
2
Request an Access Token
▼
Send a POST request to the token endpoint using Basic Authentication. The client_id and client_secret are Base64-encoded in the Authorization header:
curlcurl -X POST https://qa.api.nuvy.ai/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
-d "grant_type=client_credentials"
Or, using the curl shorthand for Basic Auth:
curlcurl -X POST https://qa.api.nuvy.ai/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-d "grant_type=client_credentials"
The -u flag in curl automatically encodes the credentials in Base64 and sends them as a Basic Authorization header.
3
Receive the Token
▼
A successful request returns a JSON response with the access token:
JSON{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"token_type": "Bearer",
"expires_in": 3600
}
| Field | Description |
|---|---|
| access_token | The JWT token to use in API requests |
| token_type | Always "Bearer" |
| expires_in | Token lifetime in seconds |
4
Use the Token
▼
Include the access token in the Authorization header of every API request:
curlcurl -X GET https://qa.api.nuvy.ai/your/endpoint \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..."
5
Code Examples
▼
Node.js
JavaScriptconst response = await fetch('https://qa.api.nuvy.ai/oauth2/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': 'Basic ' + btoa(clientId + ':' + clientSecret)
},
body: 'grant_type=client_credentials'
});
const { access_token } = await response.json();
Python
Pythonimport requests
from requests.auth import HTTPBasicAuth
response = requests.post(
'https://qa.api.nuvy.ai/oauth2/token',
auth=HTTPBasicAuth(client_id, client_secret),
data={'grant_type': 'client_credentials'}
)
access_token = response.json()['access_token']
Java
JavaString credentials = Base64.getEncoder()
.encodeToString((clientId + ":" + clientSecret).getBytes());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://qa.api.nuvy.ai/oauth2/token"))
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Authorization", "Basic " + credentials)
.POST(BodyPublishers.ofString("grant_type=client_credentials"))
.build();
HttpResponse<String> response = client.send(request,
BodyHandlers.ofString());
6
Token Renewal
▼
Tokens are short-lived. Your application should:
- Cache the token and reuse it until it expires
- Monitor the expires_in value and request a new token before expiration
- Handle 401 responses by requesting a fresh token and retrying the request
Do NOT request a new token for every API call. Cache and reuse until expiration.
7
Error Handling
▼
| Status | Description | Action |
|---|---|---|
| 400 | Invalid request (missing or wrong grant_type) | Check that grant_type=client_credentials |
| 401 | Invalid credentials | Verify client_id and client_secret |
8
Security Best Practices
▼
- Store credentials in environment variables or a secrets manager, never in source code
- Use HTTPS for all requests (enforced by Nuvy API)
- Rotate your client_secret periodically
- Implement token caching to minimize token requests
- Never log access tokens or credentials
⚙
Environments
▼
| Environment | Token Endpoint |
|---|---|
| QA | https://qa.api.nuvy.ai/oauth2/token |
| Production | https://prd.api.nuvy.ai/oauth2/token |
Use the QA environment for development and testing. Switch to Production only when ready for go-live.
API Reference
Technical specification for the OAuth2 token endpoint
POST
https://qa.api.nuvy.ai/oauth2/token
Returns an access token using the OAuth2 client credentials flow. Requires Basic authentication with client_id and client_secret.
Authentication
| Type | Details |
|---|---|
| Basic Auth | Base64 encoded client_id:client_secret |
Headers
| Header | Value | Required |
|---|---|---|
| Content-Type | application/x-www-form-urlencoded | Yes |
| Authorization | Basic {base64(client_id:client_secret)} | Yes |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| grant_type | string | Yes | Must be client_credentials |
Response (200 OK)
JSON{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"token_type": "Bearer",
"expires_in": 3600
}
Error Responses
| Status | Meaning |
|---|---|
| 400 Bad Request | Invalid or missing grant_type parameter |
| 401 Unauthorized | Invalid client_id or client_secret |
curl Generator
Enter your credentials to generate a ready-to-use curl command. Copy and run it in your terminal.
This tool only generates the command locally. Your credentials are never sent to any server from this page.