Calling the API with your own keys: Evren and tool servers

Some models and tool servers on the platform run on your own keys. Evren models use your Evren key. GitHub, Context7 and O’Reilly use your own token. You keep those keys on My variables, and an API call never carries them: the gateway reads them for the person the call identifies, on each call. So the one thing a script must get right is who it is.

The figure above compares the same Evren request from aimo, from the VS Code extension and from an app of your own. This article shows how to call the API as yourself, save your keys, and call Evren models and tool servers with them. Every command below was run against a live installation on 30 September 2026, and the answers quoted are the ones it gave.

Who does what

How a call finds your key

1. Your script sends your personal platform key, gpk_…, as the Bearer.
2. The gateway resolves that key to you. Your quota, rate limits and policy apply.
3. It reads your Evren key or your tool variable from your vault.
4. It sends that key to Evren or to the tool server, for this one call.

Your script only ever holds the personal platform key. A team or service key cannot do this: it names a team, not a person, so there is no vault to read.

Part A: once, for each person

A1. Get your personal API key

The quickest way is the console. Sign in, open My variables (/vault) and press Create my API key on the My API key card at the top.

• The new key appears with a Copy button. Load it into your shell as BOSPHORUS_KEY.
• A copy is kept in your own vault, so Show key gives you the same key again later. It is shown only to you, after you sign in.
• Replace issues a new key; the old one stops working at once, for every script that uses it. Remove revokes the key and deletes the copy.
• The key is named user:<your address>#vault. Creating, replacing or removing it never touches the keys your editor extension or your agents already hold.

Treat it like a password: anyone holding it acts as you, on your own Evren and tool keys. The check at the end of this section works for a key from either route.

From a terminal instead

If your account cannot open the console, or you would rather script it, mint the key from a sign-in with your company account, using a device code. You need curl and jq. First read how your installation signs people in:

GW=https://ai.corp.example
CFG=$(curl -s $GW/api/identity/config)
echo "$CFG" | jq '{entra: (.entra != null), oidc: .oidc.provider}'

If entra is true, the installation signs in with Microsoft Entra ID:

TENANT=$(echo "$CFG" | jq -r .entra.tenantId)
CLIENT=$(echo "$CFG" | jq -r .entra.clientId)
SCOPE=$(echo "$CFG" | jq -r .entra.scope)
DA=https://login.microsoftonline.com/$TENANT/oauth2/v2.0/devicecode
TE=https://login.microsoftonline.com/$TENANT/oauth2/v2.0/token

If oidc is generic, it signs in with its own OpenID Connect provider, such as Keycloak, and the same document names the endpoints:

CLIENT=$(echo "$CFG" | jq -r .oidc.clientId)
SCOPE="openid profile email $(echo "$CFG" | jq -r .oidc.apiScope)"
DA=$(echo "$CFG" | jq -r .oidc.endpoints.deviceAuthorization)
TE=$(echo "$CFG" | jq -r .oidc.endpoints.token)

Then start the sign-in:

DC=$(curl -s $DA -d client_id=$CLIENT --data-urlencode "scope=$SCOPE")
echo "$DC" | jq -r '.message // .verification_uri_complete'

Open the address it prints, enter the code if one is shown, and sign in. Then, in the same terminal, collect the token and exchange it for your key:

TOKEN=$(curl -s $TE -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=$CLIENT -d device_code=$(echo "$DC" | jq -r .device_code) | jq -r .access_token)
curl -s -X POST "$GW/api/identity/token?client=api" -H "Authorization: Bearer $TOKEN" | jq -r .key.key

• The full key is printed once and no copy is kept. Keep it in a password manager and load it into your shell as BOSPHORUS_KEY.
• ?client=api gives this key its own name, user:<your address>#api, so the keys your editor extension or your agents already hold keep working.
• Asking again answers existing key — the full key is shown only at mint; pass ?rotate=true to reissue. Adding &rotate=true revokes this key and issues a new one, and touches no other key.
• For a quick test you can send the sign-in token itself, $TOKEN, as the Bearer. It is treated as you for about an hour, as long as you already have a personal key.

Check who the platform thinks you are:

curl -s $GW/api/identity/me -H "Authorization: Bearer $BOSPHORUS_KEY" | jq .user.email

It prints your address. With a team key it prints null, and the answer’s note reads no user identity presented.

A2. Save your keys on My variables

Sign in to the console and open My variables (/vault).

• Evren keys: paste your LLM key, the one that starts evren_llm_, and press Save. The Platform key, evren_plt_…, is optional and only shows your balance. A key that starts evren_mdl_ is the wrong kind and is refused. Saving your LLM key accepts Evren’s terms of use on your behalf, and again when Evren publishes a new version; your administrator can switch that off.
• Tool servers: every server that takes a personal value lists it with a field of its own. Save a value for each server you use. Required ones say so until you do.

The Evren key can also be managed from a script with your personal key. PUT saves it, GET shows its state with your quota and balance, and DELETE removes it (add ?kind=llm or ?kind=platform to remove only one):

jq -n --arg k "$EVREN_LLM_KEY" '{api_key: $k}' |
  curl -s -X PUT $GW/api/identity/evren-key \
    -H "Authorization: Bearer $BOSPHORUS_KEY" -H 'Content-Type: application/json' -d @- | jq
curl -s $GW/api/identity/evren-key -H "Authorization: Bearer $BOSPHORUS_KEY" | jq 'keys'

The GET answers with four parts: llm, platform, quota and balance.

Part B: calling the API

B1. Evren models

Evren models carry the EV/ prefix. Every call uses your Evren key and your Evren account’s credits:

curl -s $GW/v1/models -H "Authorization: Bearer $BOSPHORUS_KEY" | jq -r '.data[].id' | grep '^EV/'

curl -s $GW/v1/chat/completions -H "Authorization: Bearer $BOSPHORUS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EV/deepseek-v4-flash","messages":[{"role":"user","content":"Merhaba"}]}' \
  | jq -r '.choices[0].message.content'

curl -s $GW/v1/embeddings -H "Authorization: Bearer $BOSPHORUS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EV/qwen3-embedding-8b","input":"Merhaba dünya"}' | jq '.data[0].embedding | length'

On the day this was written the chat answered Merhaba! Size nasıl yardımcı olabilirim? and the embedding had 4096 dimensions. Each answer’s usage also carries an evren block with the credits Evren held and has left, and the model it routed to.

The same works from any OpenAI SDK; only the address and the key change:

import os
from openai import OpenAI

client = OpenAI(base_url="https://ai.corp.example/v1", api_key=os.environ["BOSPHORUS_KEY"])
reply = client.chat.completions.create(
    model="EV/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Merhaba"}],
)
print(reply.choices[0].message.content)

The Evren models on the day this was written:

/v1/models always shows the current list for you.

B2. A tool server over plain HTTP

One tool call is one POST: the tool’s arguments are the JSON body, and the gateway adds your value from your vault on the way to the server. This searches O’Reilly with your own token:

curl -s -X POST $GW/api/mcp/oreilly/tools/search_oreilly_content \
  -H "Authorization: Bearer $BOSPHORUS_KEY" -H 'Content-Type: application/json' \
  -d '{"query":"kubernetes networking"}' | jq '{isError, result: (.result | .[0:200])}'

The answer is {"result": "…", "isError": false}. To see a server’s tools and their arguments, read its description with the same key:

curl -s $GW/api/mcp/oreilly/openapi.json -H "Authorization: Bearer $BOSPHORUS_KEY" | jq '.paths | keys'

For O’Reilly it lists one path, /tools/search_oreilly_content.

B3. A tool server from an MCP client

MCP clients such as Claude Code use the relay address and the same key. No tool token goes into the file:

"oreilly": {
  "type": "http",
  "url": "https://ai.corp.example/api/mcp/oreilly",
  "headers": {
    "Authorization": "Bearer ${BOSPHORUS_KEY}"
  }
}

In aimo for VS Code there is nothing to configure: once you are signed in, it reaches the same servers the same way.

Which credential to send

What the platform promises about your keys

• A key is read from your vault on each of your calls and sent only to the provider or server it belongs to. There is no cache: a change applies to the next call.
• It is never in the model’s context, never in a log line, and never in the audit trail. For a tool call the audit row records the variable’s name only.
• Tool-server values are kept in your own OpenBao folder where your installation runs OpenBao, and sealed in the platform database otherwise. Evren keys are stored encrypted in the platform database.
• Model calls count against your quota and rate limits. Model calls and tool calls both appear under your name on the activity page.
• Your personal platform key acts as you, with your keys. Treat it like a password, and rotate it if it may have leaked.

When something is not right