Authentication

Authentication is coming in Phoenix 5.0 and currently in a feature branch

By default Phoenix deploys with authentication disabled as you may be just trying Phoenix for the very first time or have Phoenix deployed in a VPC. However you might want to further protect access to your data via authentication. Below are the steps.

Authentication will stop collecting traces and block all API access until API keys are created. For that reason we recommend scheduling some downtime if you have already deployed phoenix.

Setup

To enable authentication on your Phoenix, you will have to set two environment variables:

Variable	Description	Example Value
PHOENIX_ENABLE_AUTH	Set to True to enable authentication on your platform	True or False
PHOENIX_SECRET	A long string value that is used to sign JWTs for your deployment. It should be a good mix of characters and numbers and should be kept in a secret store of some kind.	3413f9a7735bb780c6b8e4db7d946a492b64d26112a955cdea6a797f4c833593

Deploy Phoenix with the above two environment variables set. You will know that you have setup authentication correctly if the UI navigates to to a login screen.

By default Phoenix will create an admin user account. To get started:

1. Log in as the admin user. The email should be admin@localhost and the password will be admin

2. Set a new password for admin. You will be prompted to set a new password. Use a sufficiently complex password and save it in a safe place.

3. Go to the settings page on the left nav and create your first system API key. This API key can be used to log traces, use the Phoenix client, and programmatically hit Phoenix's APIs. Store the system API key in a safe place.

4. In your application code, make sure to set the proper authentication headers with the system API key. Phoenix respects headers in the form of bearer auth, meaning that you should set the header in the form Authorization: Bearer <token>. Note that if you are using the Phoenix Client or Phoenix Otel, you simply need to set the PHOENIX_API_KEY environment variable.

Re-deploy your application with the API key created above and you will see traces stream in as before.

User Management

Users can be added and removed from a Phoenix instance with authentication enabled. Users have one of two roles admin or member, see permissions below to learn more about the permissions for each role.

Only admins can manage phoenix users. They can add, delete, and reset the passwords of other members. To manage users go to the /settings page.

Deleting a user results in permanently blocking them from phoenix. The action cannot be undone and the user cannot be reactivated with the same email or username. Please be careful when deleting users.

Permissions

This section outlines the specific actions that users can perform based on their assigned roles within the system: Admin and Member. The permission matrix is divided into two main categories:

• Mutations: Operations that allow users to create, update, or delete data within the system.

• Queries: Operations that enable users to retrieve or view data from the system.

Mutations

Mutations are operations that enable users to create, update, or delete data within the system. This permission matrix ensures that only authorized roles can execute sensitive actions, such as managing users and API keys, while allowing members to perform essential account-related updates like changing their own passwords and usernames.

Neither an Admin nor Member is permitted to change email addresses.

Action	Admin	Member
Create User	Yes	No
Delete User	Yes	No
Change Own Password	Yes	Yes
Change Other's Password	Yes	No
Change Own Username	Yes	Yes
Change Other's Username	Yes	No
Change Own Email	No	No
Change Other's Email	No	No
Create System API Keys	Yes	No
Delete System API Keys	Yes	No
Create Own User API Keys	Yes	Yes
Delete Own User API Keys	Yes	Yes
Delete Other's User API Keys	Yes	No

Queries

Queries are operations that allow users to retrieve and view data from the system.

This table only shows actions that a Member is not permitted to do. Actions without restrictions are omitted.

Action	Admin	Member
List All System API Keys	Yes	No
List All User API Keys	Yes	No
List All Users	Yes	No
Fetch Other User's Info, e.g. emails	Yes	No

API Keys

There are two kinds of API keys in Phoenix: system and user.

System Keys

System keys act on behalf of the system as a whole rather than any particular user. They can only be created by admins, are not meaningfully associated with the admin who creates them except for auditing purposes, and do not disappear if that admin is deleted. A system key would be the recommended kind of key to use in programmatic interactions with Phoenix that do not involve a user (e.g., automated flows querying our REST APIs).

User Keys

User API keys are associated with and act on behalf of the user to which they are issued. That user has the ability to view and delete their own user keys, and if the user is deleted, so are all of their associated user keys. A user might create their own user key into order to run an experiment in a notebook, for example.

Setting and Using API Keys with Environment Variables

Phoenix API keys can be set with the PHOENIX_API_KEY environment variable:

export PHOENIX_API_KEY=<SYSTEM-OR-USER-KEY>

If authentication is enabled on Phoenix, all interactions with the server need to include an authorization header. Phoenix will read the PHOENIX_API_KEY environment variable, and automatically include it as an authorization header. Interactions with Phoenix include:

• Using phoenix.Client

• Runing experiments

• Sending OpenInference traces (more details below)

Sending OpenInference traces

API Keys also need to be included on OpenInference traces sent to the Phoenix server. If you've set the PHOENIX_API_KEY environment variable, the phoenix.otel module will automatically include an authorization header with the API key:

from phoenix.otel import register

tracer_provider = register()

Alternatively, you can explicitly set the authorization header on the exporter if using OpenTelemetry primitives directly.

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

endpoint = "http://127.0.0.1:6006/v1/traces"
tracer_provider = trace_sdk.TracerProvider()
exporter = OTLPSpanExporter(
    endpoint, 
    headers={"authorization": "Bearer <SYSTEM-OR-USER-KEY>"},
)
tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))

If setting authorization headers explicitly, ensure that the header field is lowercased to ensure compatibility with sending traces via gRPC

Password Recovery

The password recovery methods described in this section apply when recovering a locally authenticated user's password. To recover a password for a user logged in via a third-party identity provider such as Google

With SMTP (Simple Mail Transfer Protocol)

Using SMTP ensures that your password recovery emails are delivered reliably and securely. SMTP is the standard protocol for sending emails, making sure that you receive the reset link promptly in your inbox.

Without SMTP

If SMTP is not configured, you have a few options to recover your forgotten password:

• Contact an administrator and request that they reset your password. Admins can reset user passwords on the ./settings page.

• As a last resort, you can manually update the database tuple that contains your password salt and hash.