Authentication

Rivet uses token-based authentication for every API request. Your Rivet account team will issue an API token for each environment. Include that token in the Authorization header on every request you send to the Rivet API.

Header Format

Rivet expects the literal Token scheme followed by a space and your API key:

Authorization: Token YOUR_API_KEY

Authenticated Request Example

The example below shows a minimal authenticated payment optimization request using an environment variable:

Authenticated Optimization Request 
curl \
    https://ASSIGNED_RIVET_API_HOSTNAME/v1/transaction_payloads \
    --request POST \
    --header "Authorization: Token 53084bad-c316-448c-bccf-9c323efd1916" \
    --header "Content-Type: application/json" \
    --data-raw '{
      "action": "OPTIMIZE_SALE",
      "payload": {...}
    }'

Authentication Requirements

Header Required Example Description
Authorization Yes Authorization: Token YOUR_API_KEY Required on every HTTPS request to the Rivet API.

Best Practices

  • Store tokens in environment variables - Load them from deployment secrets or your server runtime, not hard-coded strings
  • Keep tokens server-side - Rivet authentication is intended for server-to-server requests, not public browser clients
  • Use separate tokens per environment - Keep sandbox and production credentials isolated
  • Rotate compromised tokens immediately - Contact Rivet if you suspect a token has been exposed

Authentication Failures

If authentication fails, the API returns an HTTP error status along with response metadata describing the problem.

HTTP Status When it happens
401 Missing header, malformed header, or invalid API token
403 Valid token, but it is not authorized for the requested resource or environment
Unauthorized Response Example 
{
  "_metadata": {
    "success_flag": false,
    "error_message": "A valid API authorization token is required.",
    "error_code": 401,
    "error_key": "access_denied",
    "processing_time_ms": 3
  },
  "data": {}
}

Next Step

Once authentication is configured, continue to the Submit Transaction Payload reference to start sending transactions to Rivet for optimization.

Top