Authentication
Exchange your service account's credentials for an access token and use it.
The API uses the OAuth 2.0 client credentials flow: your integration exchanges its service account's client ID and secret for a short-lived access token, and sends that token with every request. Once the access token expires, use the refresh token to obtain a new access token.
Token endpoint: https://api.zympler.com/v1beta/oauth/token
1. Get an access token
curl
curl -X POST "https://api.zympler.com/v1beta/oauth/token" \
-d grant_type=client_credentials \
-d client_id="$ZYMPLER_CLIENT_ID" \
-d client_secret="$ZYMPLER_CLIENT_SECRET"Rust
#[derive(serde::Deserialize)]
struct TokenResponse {
access_token: String,
expires_in: u64,
refresh_token: String,
}
let client_id = std::env::var("ZYMPLER_CLIENT_ID")?;
let client_secret = std::env::var("ZYMPLER_CLIENT_SECRET")?;
let response: TokenResponse = reqwest::Client::new()
.post("https://api.zympler.com/v1beta/oauth/token")
.form(&[
("grant_type", "client_credentials"),
("client_id", client_id.as_str()),
("client_secret", client_secret.as_str()),
])
.send()
.await?
.error_for_status()?
.json()
.await?;
let token = response.access_token;Python
import os
import requests
response = requests.post(
"https://api.zympler.com/v1beta/oauth/token",
data={
"grant_type": "client_credentials",
"client_id": os.environ["ZYMPLER_CLIENT_ID"],
"client_secret": os.environ["ZYMPLER_CLIENT_SECRET"],
},
timeout=30,
)
response.raise_for_status()
token = response.json()["access_token"]The response contains the access_token and when it expires; see Obtain an oauth token for all fields.
You can also send the client ID and secret as HTTP Basic authentication instead of in the body, with only
grant_type=client_credentialsin the body. And when the response includes a refresh token, you can exchange it for a new access token withgrant_type=refresh_token&refresh_token=….
2. Send it with every request
Put the token in the Authorization header:
Authorization: Bearer <access_token>
The examples in this documentation read it from $ZYMPLER_TOKEN (curl) or a token variable (Rust and Python).
3. Refresh the access token
Once the access token is about to expire, the refresh token from the initial request can be used to obtain a new access token.
curl
curl -X POST "https://api.zympler.com/v1beta/oauth/token" \
-d grant_type=refresh_token \
-d refresh_token="$ZYMPLER_REFRESH_TOKEN"Rust
#[derive(serde::Deserialize)]
struct TokenResponse {
access_token: String,
expires_in: u64,
refresh_token: String,
}
let refresh_token = std::env::var("ZYMPLER_REFRESH_TOKEN")?;
let response: TokenResponse = reqwest::Client::new()
.post("https://api.zympler.com/v1beta/oauth/token")
.form(&[
("grant_type", "refresh_token"),
("refresh_token", refresh_token.as_str()),
])
.send()
.await?
.error_for_status()?
.json()
.await?;
let token = response.access_token;Python
import os
import requests
response = requests.post(
"https://api.zympler.com/v1beta/oauth/token",
data={
"grant_type": "refresh_token",
"refresh_token": os.environ["ZYMPLER_REFRESH_TOKEN"],
},
timeout=30,
)
response.raise_for_status()
token = response.json()["access_token"]Good to know
- Reuse the token until it's about to expire, and only then request a new one. Requesting a token for every API call is slow and may be rate-limited.
- The refresh token can be only used once. When using the
refresh_tokenflow, update the stored refresh token with the refresh token returned from the refresh call. - A
401 Unauthorizedmeans the token is missing, invalid or expired: request a new one and retry once. - A
403 Forbiddenmeans your service account doesn't have access to that resource. Email support@zympler.com if you think they should.