Authentication

RecVue APIs use token-based authentication. Exchange the credentials of a RecVue user for an access token, then send that token in the access_token header on every API call.

Use a dedicated integration user. Create a separate user in your tenant for each integration and assign it only the roles it needs. API access follows that user's role permissions.

Base URL

EnvironmentBase URL
Productionhttps://{tenant}.recvue.com/api
Test / Sandboxhttps://{tenant}-test.recvue.com/api

{tenant} is your company short name, e.g. acme. The host name identifies your tenant, so you don't need to send a tenant header.

Step 1: Get an access token

Send a GET request to the token endpoint with your username and password, base64-encoded as username:password, in the Authorization header.

curl -X GET "https://{tenant}.recvue.com/api/v2.0/token" \
  -H "Authorization: $(printf '%s' '[email protected]:YourPassword' | base64)"

Response (200)

{
  "access_token": "eyJraWQiOiJ...",
  "expiration_date": "Tue Nov 04 10:15:00 UTC 2026"
}
FieldDescription
access_tokenToken to send on every API request.
expiration_dateWhen the token expires (UTC). Tokens are valid for about 1 hour.

The token endpoint is the same for every API version. Always request tokens from /api/v2.0/token, including when you call v2.1 or v3.0 endpoints. There is no /api/v2.1/token or /api/v3.0/token.

Step 2: Call the API

Send the token in the access_token header. Don't add a Bearer prefix.

curl -X GET "https://{tenant}.recvue.com/api/v3.0/orders?page=1&size=10" \
  -H "access_token: eyJraWQiOiJ..." \
  -H "Content-Type: application/json"

Token lifetime and renewal

  • Tokens expire after about 1 hour. Check expiration_date.
  • No refresh token is issued. Request a new token from the token endpoint before the current one expires.

Errors

StatusWhenBody
401 UnauthorizedMissing or malformed Authorization header, invalid username or password, or a locked or inactive user{"error": "<message>"}
401 UnauthorizedMissing, invalid or expired access_token on an API callGateway error response

Check statusCode in the response body. Some endpoints return HTTP 200 for business or validation failures and put the failure status in the body.

SCIM provisioning authentication

The SCIM 2.0 user provisioning APIs (/api/scim/Users) use a separate OAuth 2.0 client credentials flow. Contact RecVue Support to get a client_id and client_secret for your tenant.

Get a SCIM token

curl -X POST "https://{tenant}.recvue.com/api/scim/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Alternatively, send the client ID and secret as an HTTP Basic header (Authorization: Basic base64(client_id:client_secret)) with only grant_type=client_credentials in the body.

Response (200)

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Call SCIM endpoints with the token as a Bearer token:

curl -X GET "https://{tenant}.recvue.com/api/scim/Users?startIndex=1&count=10" \
  -H "Authorization: Bearer eyJhbGciOi..."
RecVue APIsSCIM APIs
Token endpointGET /api/v2.0/tokenPOST /api/scim/oauth/token
CredentialsUsername and passwordClient ID and secret
Header on callsaccess_token: <token>Authorization: Bearer <token>
LifetimeAbout 1 hourexpires_in seconds (default 3600)