API Authentication

Learn how to authenticate with the Qovery API

Overview

The Qovery API uses Bearer token authentication. You need an API token to make authenticated requests to the API.

Creating an API Token

Via Qovery Console

1. Log in to the Qovery Console
2. Navigate to Organization Settings
3. Click on API Tokens
4. Click Generate Token
5. Give your token a descriptive name
6. Set token permissions and expiration
7. Click Create and save the token securely

API tokens are displayed only once. Store them securely - treat them like passwords.

Token Scopes

When creating a token, you can configure these scopes:

Scope	Description
Admin	Full access to all resources
Read	Read-only access to resources
Deploy	Can trigger deployments
Write	Can create and update resources

Making Authenticated Requests

Include your API token in the Authorization header:

curl -H "Authorization: Token YOUR_API_TOKEN" \
  https://api.qovery.com/organization

Authentication Methods

Using cURL

export QOVERY_API_TOKEN="your-api-token"

curl -X GET "https://api.qovery.com/organization" \
  -H "Authorization: Token ${QOVERY_API_TOKEN}" \
  -H "Content-Type: application/json"

Using Python

import requests

QOVERY_API_TOKEN = "your-api-token"
BASE_URL = "https://api.qovery.com"

headers = {
    "Authorization": f"Token {QOVERY_API_TOKEN}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{BASE_URL}/organization",
    headers=headers
)

print(response.json())

Using JavaScript/TypeScript

const QOVERY_API_TOKEN = 'your-api-token';
const BASE_URL = 'https://api.qovery.com';

const headers = {
  'Authorization': `Token ${QOVERY_API_TOKEN}`,
  'Content-Type': 'application/json'
};

fetch(`${BASE_URL}/organization`, {
  method: 'GET',
  headers: headers
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Using Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    token := os.Getenv("QOVERY_API_TOKEN")
    url := "https://api.qovery.com/organization"

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        panic(err)
    }

    req.Header.Add("Authorization", "Token "+token)
    req.Header.Add("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

Using Official SDKs

Python SDK

from qovery import Qovery

# Initialize client
client = Qovery(token="your-api-token")

# Get organization
org = client.organization.get()
print(f"Organization: {org.name}")

# List projects
projects = client.projects.list()
for project in projects:
    print(f"Project: {project.name}")

JavaScript/TypeScript SDK

import { Qovery } from 'qovery';

// Initialize client
const client = new Qovery({
  apiToken: 'your-api-token'
});

// Get organization
const org = await client.organization.get();
console.log(`Organization: ${org.name}`);

// List projects
const projects = await client.projects.list();
projects.forEach(project => {
  console.log(`Project: ${project.name}`);
});

Environment Variables

Store your API token securely using environment variables:

Linux/macOS

Add to your .bashrc, .zshrc, or .env file:

export QOVERY_API_TOKEN="your-api-token"

Load environment variables:

source ~/.bashrc

Windows PowerShell

$env:QOVERY_API_TOKEN = "your-api-token"

Docker

Pass as environment variable:

docker run -e QOVERY_API_TOKEN="your-api-token" your-image

Kubernetes

Create a secret:

kubectl create secret generic qovery-token \
  --from-literal=token="your-api-token"

Use in deployment:

apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
  - name: app
    image: your-image
    env:
    - name: QOVERY_API_TOKEN
      valueFrom:
        secretKeyRef:
          name: qovery-token
          key: token

Authentication Errors

401 Unauthorized

Token is missing or invalid:

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

Solution: Verify your token is correct and included in the Authorization header.

403 Forbidden

Token doesn’t have required permissions:

{
  "status": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions to access this resource"
}

Solution: Check token scopes and ensure you have the required permissions.

Token Security Best Practices

Never commit tokens to version control

Always use environment variables or secrets management tools. Add .env files to .gitignore.

Use minimal required scopes

Create tokens with only the permissions needed for their specific use case.

Rotate tokens regularly

Set expiration dates and rotate tokens periodically for security.

Monitor token usage

Regularly review API token activity in the Qovery Console.

Revoke unused tokens

Delete tokens that are no longer needed or potentially compromised.

Use separate tokens per environment

Create different tokens for development, staging, and production.

Testing Authentication

Test your authentication setup:

curl -X GET "https://api.qovery.com/organization" \
  -H "Authorization: Token ${QOVERY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -w "\nHTTP Status: %{http_code}\n"

Expected response:

{
  "id": "org-id",
  "name": "My Organization",
  "created_at": "2024-01-01T00:00:00.000Z",
  ...
}

Next Steps

API Examples

See practical examples of using the authenticated API