Skip to main content

Account and Login

This guide covers creating an account, signing in, and creating your first API key in Cirata Symphony.

Signing In​

Using the User Interface​

Navigate to https://your-symphony-instance.com in your web browser. You will be redirected to your organization's configured OpenID Connect (OIDC) identity provider (such as Keycloak, Okta, Azure AD, Auth0, or Google Workspace). Sign in with your organizational credentials.

Once authenticated, the Symphony user interface will present you with the dashboard view and menu options.

Using the CLI​

Use the cirata login command to authenticate from the command line, specifying the hostname of your Symphony instance:

cirata login --address your-symphony-instance.com

The CLI opens your browser to authenticate with your identity provider, then creates an API Key for you in Symphony and saves its token to the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) so that subsequent cirata commands authenticate automatically. In environments without a credential store, use --insecure-storage to save the token to the local config file instead.

Managing Stored Credentials​

The cirata credential command lets you list and manage stored credentials for both the CLI and extensions:

cirata credential list      # List all stored credentials
cirata credential remove ext-weather  # Remove a specific credential
cirata credential clear     # Remove all stored credentials

See the CLI Reference for full details.

API Keys and Tokens​

Programmatic access to Symphony uses two related concepts that are easy to confuse:

  • An API Key is what Symphony stores. It defines a set of capabilities—the allow permissions that establish the security boundary for anything acting as that key. API Keys have a name, an expiry, and optional notes so you can tell them apart in the Account → API Keys list.
  • A token is the short opaque string that a client or extension uses to contact Symphony with the API Key's permissions. Presenting a token proves the holder is authorised to act as the API Key; the token also carries the address of the Symphony instance so the client knows where to connect.

In short: an API Key is a set of permissions; a token is the credential that asserts the right to use it. Users create API Keys in the UI, and are issued a token to pass to the extension, CLI, or script that needs to operate with those permissions.

The Symphony UI lists and manages API Keys. The SYMPHONY_TOKEN environment variable, the Authorization: Bearer <token> HTTP header, and the token argument accepted by the extension libraries all expect a token—the credential that was shown once when the API Key was created.

warning

A token is a secret. A token authenticates as the API Key's holder. Anyone who obtains it can act with the API Key's full capabilities until the key is revoked or expires. Treat tokens as you would treat a password. Do not share tokens over chat, email, screenshots, screen shares, or commit them to source control.

Symphony does not store tokens. Only a one-way hash is kept server-side, so the token cannot be recovered or re-displayed after the API Key is created. If you lose the token, the only recourse is to revoke the API Key and create a new one.

Capture the token at creation time into a suitable secret store—a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault), a Kubernetes Secret, your CI system's encrypted variables, or the OS credential store—before closing the dialog.

Creating an API Key​

API Keys are required for running extensions, using the client libraries, and calling the REST API.

  1. Navigate to Account → API Keys in the Symphony UI.
  2. Click Create API Key.
  3. Give the key a descriptive name (e.g. "My Extension" or "CI Pipeline") and an expiry date.
  4. Select the capabilities the key needs:
    • For full access, allow cirata.> for both provide and access.
    • For extension-specific access, scope to cirata.extensions.<name>.>.
  5. Click Create.
  6. Copy the token that is displayed. It is only shown once and cannot be retrieved later—if you lose it, revoke the API Key and create a new one.
info

If RBAC is enabled, the capabilities you can assign to an API Key are limited by your assigned roles. See Role-Based Access Control for details.

warning

Each API Key identifies a single extension. Using the same token for more than one running extension—including multiple instances of the same extension—causes them to share an identity in Symphony, and only the most recently registered will be visible. Generate a separate API Key for each extension.

Using Your Token​

Once an API Key is created, pass its token to whatever client or extension should act with the API Key's permissions:

  • Extensions resolve the token from the SYMPHONY_TOKEN environment variable. Set it in the extension's environment—an .env file during development, a Kubernetes Secret, a systemd unit, or a container image build arg. The language-specific guides (Python, Java, Go, Rust) describe exactly how each SDK reads it and what other fallbacks are supported.
  • REST API callers send Authorization: Bearer <token> with each request. See the REST API reference for the full list of endpoints and status codes.
  • The cirata CLI creates its own API Key on first use of cirata login and stores the resulting token in the OS credential store. Use cirata credential list to inspect stored tokens and cirata account to view the current token's capabilities. See the CLI Reference.

Revoke an unused or compromised API Key at any time from Account → API Keys. Any token issued from it stops working immediately.

Session Idle Timeout​

If you are inactive in the Symphony UI for a period of time (default: 30 minutes), your session will be allowed to expire. When this happens, you will be redirected to the login page with a notification that your session has expired. Simply sign in again to continue.

The idle timeout duration is configurable by administrators in Admin → Settings.

Signing Out​

In the Symphony UI, click your user avatar or name in the top-right corner and select Sign Out. This ends your browser session.

From the CLI:

cirata logout

See Also​