API Keys

Administrators Only

This setting is only visible to users with the Administrator role.

The Ayunis API allows your organization to use its language models outside of the regular web interface — for example, directly from a line-of-business application, an internal portal, or an automation workflow. Before an external application can identify itself to Ayunis, it needs an API key. As an administrator you create the key and pass it on securely to the relevant party — typically your IT department, an IT service provider, or the vendor of the system you are connecting.

What is the API for?

Typical use cases in public administration include:

• Connecting line-of-business systems — for example, so that your document management system can automatically summarize, classify or tag incoming correspondence.
• Automating recurring tasks — such as automatically translating or pre-checking large numbers of documents in an internal script.
• Integration into your own applications — when you want to offer Ayunis features in an internal staff portal or a custom web application.
• Workflows with automation tools — for example with tools like n8n, Make or your own Python scripts, to automate recurring processes.

You don’t need to write code yourself

The API is typically used by your IT department, an IT service provider, or the vendor of the system being connected. As an administrator your role is to create the access, share it securely, and revoke it when needed.

Prerequisites

Before the API can be used, the following must be in place:

1. An API key — created in this setting.
2. A usage-based subscription (or remaining trial messages) for your organization.
3. At least one enabled model in Admin Settings → Models.

Opening API Key Settings

1. Navigate to Admin Settings → API Keys
2. You will see a list of all API keys for your organization

Creating an API Key

1. Click Create API Key
2. Enter a Name for the key (e.g. “DMS connection – building authority” or “Translation script – social services”) — this helps you recognize later what the key is used for.
3. Optionally, choose an Expiration date — after this date the key will stop working. Leave empty for a key that never expires.
4. Click Create Key

After creation, the full API key is displayed once. Copy it immediately and pass it on securely to the person or system that will use it — for example via your organization’s password manager.

Save Your Key Immediately

The full API key is only shown once at the time of creation. After you close the dialog, it cannot be retrieved again. If you lose the key, you will need to create a new one.

Understanding the Key List

Each API key in the list shows:

• Name — the name you assigned when creating the key
• Key prefix — a short preview of the key (e.g. ayu_abc1...) for identification
• Created date — when the key was created
• Expiration — when the key expires, or “Never expires”
• Status — whether the key is active or has been revoked

Revoking an API Key

If a key is no longer needed, a service provider changes, or the key has accidentally been shared with the wrong party, you can revoke it at any time:

1. Find the key in the list
2. Click the Revoke button (trash icon)
3. Confirm the action in the dialog

Immediate Effect

Revoking a key takes effect immediately. Any applications or tools using that key will stop working right away. This action cannot be undone.

Best Practices for Secure API Keys

• Use descriptive names — name keys after their purpose or the system using them (e.g. “DMS connection”, “Council information workflow”).
• One key per application or service provider — use a separate key for each application and each service provider, so you can revoke access individually without affecting other connections.
• Set expiration dates — for temporary integrations or external service providers, set an expiration date so the key becomes invalid automatically.
• Rotate keys regularly — create new keys and revoke old ones periodically.
• Share securely — only pass keys on through trusted channels (e.g. a password manager). Do not send them via email or chat.

Technical Interface

For your IT team

This section is intended for the IT department or service provider implementing the integration. As an administrator you can simply forward it — you do not need to perform these steps yourself.

Ayunis offers an OpenAI-compatible API. You can therefore use the official OpenAI libraries (Python, Node.js) and any HTTP client — only the base URL needs to be adjusted.

Base URL

https://core.ayunis.com/api/openai-compat/v1

Authentication

All requests are authenticated using the API key in the Authorization header:

Authorization: Bearer ayu_your-api-key-here

Endpoint: Chat Completions

POST /api/openai-compat/v1/chat/completions

Request Example

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "stream": false
}

You can find the value for model in Admin Settings → Models — it is shown below the display name of each model.

Key Parameters

Parameter	Type	Required	Description
model	string	Yes	Technical model identifier from the model settings.
messages	array	Yes	Conversation history, each message with role (system, user, assistant) and content.
stream	boolean	No	Set to true to receive the response as a stream of Server-Sent Events.
temperature	number	No	Controls randomness (0–2). Lower values produce more focused responses.
max_tokens	number	No	Maximum number of tokens to generate.
tools	array	No	List of tool/function definitions the model can call.
tool_choice	string	No	Controls whether the model should use tools (auto, none, or a specific function name).

Examples Using the OpenAI SDK

Python

from openai import OpenAI

client = OpenAI(
    api_key="ayu_your-api-key-here",
    base_url="https://core.ayunis.com/api/openai-compat/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello, how can you help me?"}
    ]
)

print(response.choices[0].message.content)

Node.js / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "ayu_your-api-key-here",
  baseURL: "https://core.ayunis.com/api/openai-compat/v1"
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Hello, how can you help me?" }
  ]
});

console.log(response.choices[0].message.content);

Streaming

For longer responses, streaming can be enabled to receive partial results as they are generated:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a short poem."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Rate Limits

The API is rate-limited to 60 requests per minute per client IP address. If this limit is exceeded, a 429 Too Many Requests response is returned.

Error Handling

Errors are returned in the standard OpenAI error format:

{
  "error": {
    "message": "Description of what went wrong",
    "type": "error_type",
    "code": "error_code"
  }
}

Common HTTP statuses:

HTTP Status	Meaning
401	Invalid or missing API key
403	No active subscription or quota exhausted
404	Model not found or not permitted for your organization
429	Rate limit exceeded
500	Internal server error

Credit Consumption

API requests consume credits from your organization’s allowance, just like messages sent through the web interface. The credit cost depends on the model tier and the number of tokens processed.

Next Steps

• Models — See which models are available via the API and what their technical identifiers are.
• Integrations — Connect other systems to Ayunis.