Authentication

Authenticate VIESUS Cloud API requests using the x-api-key header. Creating and managing API keys.

VIESUS Cloud authenticates every request using an API key passed as an HTTP header. There is no session, no OAuth flow, and no token expiry — just a static key on every request.

---

Header format

x-api-key: <your-api-key>

Include this header on every request to the GraphQL endpoint.

---

Examples

curl:

curl -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{"query": "query { credits { remainingCreditsThisPeriod } }"}'

Node.js (graphql-request):

import { GraphQLClient } from 'graphql-request';

const client = new GraphQLClient('https://api.viesus.cloud/graphql', {
  headers: {
    'x-api-key': process.env.VIESUS_API_KEY,
  },
});

Python (gql):

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url='https://api.viesus.cloud/graphql',
    headers={'x-api-key': 'your-api-key-here'},
)
client = Client(transport=transport, fetch_schema_from_transport=True)

PHP (GuzzleHttp):

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://api.viesus.cloud/graphql',
    'headers' => [
        'x-api-key' => 'your-api-key-here',
        'Content-Type' => 'application/json',
    ],
]);

---

Creating an API key

API keys are managed in the dashboard:

→ https://www.viesus.cloud/app/api-keys

1

Log in to your account.

2

Navigate to API Keys.

3

Click Create new key and give it a descriptive name.

4

Copy and store the key securely — it is shown only once.

If you lose the key, delete it and create a new one.

---

Best practices

Never hardcode the key in source code. Pass it through an environment variable:

VIESUS_API_KEY="your-key-here" node server.js

const apiKey = process.env.VIESUS_API_KEY;
if (!apiKey) throw new Error('VIESUS_API_KEY is not set');

Rotate keys when team members leave or if a key may have been exposed. Create a new key first, update all integrations, then delete the old key.

Use separate keys per environment (development, staging, production). This limits blast radius if a key leaks and makes it easier to track usage by environment.

---

Verifying your key

Query the credit balance — if this returns data, your key is valid:

query {
  credits {
    remainingCreditsThisPeriod
    usedCreditsThisPeriod
    periodStart
    periodEnd
  }
}

A missing or invalid key returns an authentication error in the GraphQL response.