Authentication

Conomy uses backend authentication. Your server exchanges client credentials for an access token, then sends that token as a bearer credential on protected API requests.

Required headers

Every protected request should include:

Header	Purpose
Authorization	Bearer access token returned by POST /auth.
x-api-key	API Gateway key assigned to your Conomy integration.
conomyhq-api-version	Version selector for the current API contract. Optional — defaults to v1; send 24-04-2025 for v2.
User-Agent	Application identifier used for observability and support.

Attention

Never expose clientSecret, access tokens, or x-api-key in a browser application. Keep authentication on your backend.

Token request

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/auth HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json
Accept: application/json

{
  "clientId": "{CLIENT_ID}",
  "clientSecret": "{CLIENT_SECRET}"
}

curl -X POST 'https://api.conomyhq.com/sandbox/auth' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "clientId": "{CLIENT_ID}",
    "clientSecret": "{CLIENT_SECRET}"
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/auth', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    "clientId": "{CLIENT_ID}",
    "clientSecret": "{CLIENT_SECRET}"
  }),
});

const data = await response.json();

import requests

payload = {
  "clientId": "{CLIENT_ID}",
  "clientSecret": "{CLIENT_SECRET}"
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/auth',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    },
    json=payload,
)

data = response.json()

package main

import (
	"bytes"
	"net/http"
)

func main() {
	payload := []byte(`{
  "clientId": "{CLIENT_ID}",
  "clientSecret": "{CLIENT_SECRET}"
}`)
	body := bytes.NewReader(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/auth", body)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let payload = json!({
  "clientId": "{CLIENT_ID}",
  "clientSecret": "{CLIENT_SECRET}"
});

    let response = client
        .post("https://api.conomyhq.com/sandbox/auth")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .json(&payload)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

200

{
  "accessToken": "{ACCESS_TOKEN}",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Next step

Use the token to create the first operating resources in Recipes or validate the endpoint contract in API Reference.