Skip to main content
Personal access tokens (PATs) authenticate programmatic access to Ona via the CLI or SDK.

​
Create a token

  1. Go to Personal access tokens
  2. Click “New Token”
  3. Enter a description and select expiration (30, 60, or 90 days)
  4. Choose an access level:
    • Read-only - the token can only read data. All write operations are denied.
    • Read & Write - the token can both read and modify data.
  5. Click “Create” and copy the token immediately - you won’t see it again

​
Use a token

ona login --token <your-token>
Or set the environment variable: 
export ONA_TOKEN=<your-token>
ona login

​
Permissions

Tokens inherit your user account’s permissions and can be scoped to one of two access levels:
Access levelDescription
Read-onlyCan list and retrieve resources but cannot create, update, or delete them.
Read & WriteFull access. Can perform any action your user account is allowed to perform.
The access level is set at creation time and cannot be changed afterward. To switch access levels, revoke the existing token and create a new one.

​
Security

  • Treat tokens like passwords - don’t share or store insecurely
  • Use the shortest expiration that meets your needs
  • Revoke unused tokens
  • Actions are logged in audit logs with the token ID

​
Examples

​
CI/CD integration

Authenticate your CI/CD pipeline to create and manage environments. 
name: Ona Integration
on: [push]
jobs:
  create-environment:
    runs-on: ubuntu-latest
    steps:
      - name: Create Environment
        env:
          ONA_TOKEN: ${{ secrets.ONA_PAT }}
          ONA_CLASS: some-class-id
        run: |
          ona login --token $ONA_TOKEN
          ona environment create --class-id $ONA_CLASS https://github.com/your-repo

​
Scripted environment management

Manage environments programmatically for bulk operations. 
import subprocess
import json

ONA_PAT = "your_personal_access_token"

def run_ona_command(*args):
    result = subprocess.run(
        ["ona"] + list(args),
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout.strip()

# Login using PAT
run_ona_command("login", "--token", ONA_PAT)

# List all environments
environments_json = run_ona_command("environment", "list", "-o", "json")
environments = json.loads(environments_json)

# Stop all running environments
for env in environments:
    if env['status']['phase'] == 'ENVIRONMENT_PHASE_RUNNING':
        print(f"Stopping environment {env['id']}")
        run_ona_command("environment", "stop", env['id'])

print("All running environments have been stopped.")

​
Third-party tool integration

Create environments from external tools. 
import subprocess
import json

ONA_PAT = "your_personal_access_token"

def create_environment_for_review(repo_url):
    # Login using PAT
    subprocess.run(["ona", "login", "--token", ONA_PAT], check=True)

    # Create an environment
    result = subprocess.run(
        ["ona", "environment", "create", repo_url, "--dont-wait"],
        capture_output=True,
        text=True,
        check=True
    )
    env_id = result.stdout.strip()

    # Get the environment details
    result = subprocess.run(
        ["ona", "environment", "get", env_id, "-o", "json"],
        capture_output=True,
        text=True,
        check=True
    )
    return json.loads(result.stdout)