Connect your model provider

Verdictan calls models with your own provider account. An OpenAI request uses your OpenAI key and your OpenAI credit. This is called bring your own key (BYOK).

The gateway must have a provider key before it can forward a request. A model in the Verdictan catalog is not available to you until your provider account has access to it and has credit.

Select where to keep the key

Where	Use it for
Environment variable	A test on your computer, or a gateway that gets its secrets from your own secret manager.
Saved organization secret	One key that more than one connected gateway shares.
Cloud identity	Providers such as Bedrock or Vertex AI. See Cloud Provider Configuration.

The provider key is one of three credentials. The gateway token connects the gateway to Verdictan, and the application token authorizes the requests of your app. Keep all three different.

Use a local environment variable

In the Console setup flow, select Use a local environment key. Then set the key in the terminal that will run the gateway command:

macOS or Linux

export OPENAI_API_KEY='your-openai-api-key'

Windows PowerShell

$env:OPENAI_API_KEY = 'your-openai-api-key'

The gateway reads the variable when it starts. Verdictan does not store the key. Continue with Start your gateway in the quickstart.

Reference a key in YAML

A gateway that you configure in a file finds the key through secret_key_ref in each provider target:

policy-config.yaml (provider section)

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-5.4-mini
      secret_key_ref:
        env: OPENAI_API_KEY

Use a model that your account can access. Provider Configuration has a complete file.

secret_key_ref takes one source:

Source	Reference
Environment variable on the gateway host	env: OPENAI_API_KEY
Saved organization secret	store: OPENAI_API_KEY

The env name must match the variable that you set for the gateway process. Some examples use VERDICTAN_OPENAI_API_KEY. Any name works if the variable and the reference agree. To use an external secret manager, put the key in the gateway environment and use env. Do not put a key value in YAML or in a literal authorization header.

Save a key and grant agent access

Save the key in Verdictan when more than one gateway must use it. You must have permission to manage secrets and agent access.

1. Open Secrets in the Console.
2. Select Configure next to the provider.
3. Enter your provider key. Keep the name that the Console shows unless your configuration uses a different name.
4. Save the key.
5. Go to Overview, open Route your first request, and select the Setup step.
6. If the Console shows Allow Assistant to use this key, select it.
7. Open the Try it step and send the generated request.

A saved key is not available to an agent until a role gives that agent access. The setup flow gives access to the default Assistant agent only. For each other agent, attach a role as described in the next section.

Give a different agent access

The role must contain a policy that allows the agent to read the secret. An empty role gives no access. See Roles and IAM Policies.

Attach the role to the agent, and then simulate provider access. The attach call needs a token with agents:write. The simulation needs agents:read and secrets:read. Use the API URL of your organization's region, for example https://api.us.verdictan.com for a US organization.

export VERDICTAN_API_URL='https://api.eu.verdictan.com'
export VERDICTAN_API_TOKEN='your-administrator-api-token'
export VERDICTAN_AGENT_ID='your-agent-uuid'
export VERDICTAN_ROLE_ID='your-role-uuid'

curl --fail-with-body -X POST \
  "$VERDICTAN_API_URL/v1/agents/$VERDICTAN_AGENT_ID/provider-key-access/bindings" \
  -H "Authorization: Bearer $VERDICTAN_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"role_id\":\"$VERDICTAN_ROLE_ID\"}"

curl --fail-with-body -X POST \
  "$VERDICTAN_API_URL/v1/agents/$VERDICTAN_AGENT_ID/provider-key-access/simulations" \
  -H "Authorization: Bearer $VERDICTAN_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"provider":"openai"}'

Examine the result

The simulation returns a simulation object. When access is ready, allowed is true, status is ready, and status_reason is provider_key_ready. Other reasons tell you what to correct:

status_reason	Meaning
provider_key_not_configured	No saved key exists for the provider.
provider_key_no_policy_binding	The agent has no role or policy that applies.
provider_key_policy_denied	A policy applies, but it does not allow the agent to read the key.

A simulation checks authorization only. Send one model request through the agent URL to verify the key, model access, and connection. Budgets and request rules also apply to that request.

To list bindings, send GET to the bindings URL. To remove one, send DELETE /v1/agents/{agent_id}/provider-key-access/bindings/{role_id}.

Use tags in access rules

Tags such as environment=production help a policy select the correct keys and agents. A matching tag alone does not give access. A policy must allow the operation. See Resource Tags.

Replace or revoke a key

1. Create a new key with your provider.
2. Put the new key in its source. For a saved key, select Rotate in Secrets. For an environment variable, change the value on the gateway host.
3. If the gateway reads an environment variable, stop the gateway and start it again.
4. Send a small test request through Verdictan.
5. Revoke the old key with your provider.

To stop an agent from using a saved key, remove its access binding or delete the secret. Also revoke the key with the provider, so that nobody can use it directly.

Next steps

• Provider Configuration: add models and configure routing and fallback.
• Usage Costs and Budgets: set cost limits after the first request succeeds.