Authentication and Authorization

Access control in Planton answers two questions: who are you (authentication) and what can you do (authorization). Authentication verifies identity through an OAuth provider, API key, or service account credentials. Authorization evaluates permissions using a relationship-based model that automatically inherits access through the resource hierarchy.

Authentication

Interactive Login

Users authenticate through an OAuth identity provider. The web console handles this automatically when you visit the platform. The CLI signs in through the console in your browser: it opens the console's sign-in page, and the CLI receives a sign-in of its own. If the browser is already signed in as the account you asked for, no password is typed. No client secrets are stored locally.

# Sign in (opens the browser); name the account to skip the picker
planton auth login you@example.com

# Check your current identity and whether the sign-in renews automatically
planton auth whoami

A login is checked before it reports success.

• If the platform does not accept the new sign-in, the login fails, exits non-zero, and leaves your saved sign-ins as they were.
• A sign-in renews itself while its renewal is good.
• When it can no longer be renewed, every command that needs a sign-in says whose sign-in expired, on which instance and why, and gives the exact planton auth login <email> to run.
• When the sign-in service cannot be reached, the CLI says the sign-in could not be checked, not that it expired.

You can hold several accounts per instance, and several instances:

# List every saved account, each with its own status
planton auth list

# Switch the active account on the current instance (checked, and renewed if needed)
planton auth switch other@example.com

# Switch to a different instance
planton auth use <instance>

Signing In at a Custom Domain

An organization on the Team plan can serve its console at its own address, such as planton.acme.com (see Custom Domain). Signing in there is a hand-off: the address sends you to planton.ai, you sign in as usual, and planton.ai hands you back into a session confined to that organization. The session reaches only that organization, so a page on a customer's address never holds a sign-in that works anywhere else. Inviting people and creating credentials, such as API keys, open at planton.ai, where your sign-in is the full one.

API Keys

For automation, CI/CD pipelines, and scripts that cannot use a browser-based login, Planton supports API keys.

API keys carry the permissions of the user who created them. If Alice has admin access to the production environment and creates an API key, that key has the same admin access Alice has. If Alice's permissions change, the key's effective permissions change with them.

# Create a new API key
planton iam apikey new --name "ci-pipeline"

# List existing API keys
planton iam apikey list

Key properties:

• Hashed storage — Planton stores a cryptographic hash of the key, never the plaintext. The key is displayed once at creation and cannot be retrieved afterward.
• Fingerprint — Each key has a short fingerprint (last 6 characters) for identification in the web console and CLI output.
• Expiration — Keys can be set to expire on a specific date or configured to never expire.
• Last-used tracking — Planton records when each key was last used, so you can identify unused keys for rotation or cleanup.

Service Accounts

Service accounts are machine identities for automation workloads that need to authenticate with the Planton platform. Where API keys are tied to a human user's permissions, service accounts are standalone identities with their own permission grants — purpose-built for Runners, CI/CD pipelines, and other automated systems.

Each service account is scoped to an organization and backed by a dedicated machine identity account. It uses the same API key infrastructure as user keys, so the authentication pipeline is identical: the platform sees an API key, resolves the owning identity, and evaluates permissions. The difference is that the identity belongs to a machine, not a person.

How Service Accounts Work

When you create a service account, Planton:

1. Creates the service account resource in the IAM domain
2. Auto-provisions a backing machine identity account
3. Grants the identity viewer access on the owning organization — this cascades through the permission hierarchy to secrets and variables, enabling the service account to resolve credentials at runtime

Deleting a service account cascades completely: all API keys are revoked, all permission grants are removed, and the backing identity account is deleted.

Key Management

Service account keys work like user API keys — they are displayed once at creation and stored only as a cryptographic hash. You can create multiple keys for a single service account (for key rotation without downtime) and revoke individual keys when they are no longer needed.

When Runners Use Service Accounts

When a Runner enrolls — started with a runner token, it registers itself on arrival — Planton auto-provisions a service account for that runner and mints an API key delivered in the runner's identity document. The runner uses this key to authenticate with the control plane at startup and to resolve secrets and variables at runtime. You do not need to create the service account manually — enrollment handles everything.

For details on how this fits into the runner's security model, see Runner Security Model.

Using the Web Console

Navigate to Organization Settings > Service Accounts to manage service accounts. The page shows all service accounts in the organization with their name, description, and creation date.

To create a service account, click Create Service Account and provide a name and optional description. After creation, navigate to the service account's detail page to manage its API keys.

The key creation dialog uses a two-phase flow: confirm creation, then copy the key from the one-time reveal. You must acknowledge that you have saved the key before the dialog closes — the key cannot be retrieved afterward.

Using the CLI

# List service accounts in an organization
planton sa list --org acme

# Create a service account
planton sa create --org acme --name deploy-runner --description "Production runner identity"

# View service account details
planton sa get sa_01abc123

# Create an API key for a service account
planton sa key create sa_01abc123

# List API keys belonging to a service account
planton sa key list sa_01abc123

# Revoke a specific API key
planton sa key revoke sa_01abc123 --key-id ak_01xyz789

# Delete a service account (cascades: revokes all keys, removes permissions)
planton sa delete sa_01abc123

Authenticating with an API Key

Both user API keys and service account API keys can be used to authenticate the CLI without a browser. This is useful for CI/CD environments, scripts, and any context where interactive OAuth login is not possible:

# Authenticate with an API key (user or service account)
planton auth login --api-key pak_abc123...

# Verify the authenticated identity
planton auth who

When authenticated with a service account key, planton auth who displays the service account name and organization instead of a user email. planton auth list shows these sessions as "API Key (SA)" to distinguish them from user API key sessions.

Authorization

The Model

Planton uses OpenFGA for all access control decisions. OpenFGA is an open-source fine-grained authorization engine based on Google's Zanzibar paper. Rather than maintaining simple access control lists, it evaluates permissions through relationships between users, teams, and resources.

This means Planton does not store a flat list of "Alice can access Resource X." Instead, it stores relationships — "Alice is an admin of Organization Acme" and "Organization Acme owns Environment Production" — and computes that Alice can access resources in Production because admin access flows through the ownership chain.

Why This Matters

The practical benefit is that you manage access at the right level of granularity and it propagates automatically:

• Grant someone admin on the organization → they are admin on every environment and every resource within it
• Grant someone viewer on an environment → they can view every Infra Component and service in that environment
• Grant a team admin on an environment → every member of that team (including members of nested sub-teams) inherits admin access

You do not need to manually assign permissions to each individual resource. The authorization engine computes effective permissions by traversing the relationship graph.

Resource Hierarchy

Permissions flow through a three-level hierarchy:

Each level inherits permissions from its parent:

You can also grant permissions directly on individual resources when you need more granular control.

Roles

Planton defines five standard roles that apply across most resource types:

Roles are scoped to resource types. An "Organization Admin" is a different role from a "Service Admin" — they share the same capabilities (create, update, delete) but apply to different resource types. This prevents a team that manages services from accidentally gaining access to infrastructure credentials.

Teams

Teams allow you to manage permissions for groups of people instead of individuals. A team has members, and any permission granted to the team flows to all members.

Teams support nesting — a team can include other teams as members. For example:

• Platform Engineering team includes the Infrastructure team and the SRE team
• A permission granted to Platform Engineering automatically applies to all members of Infrastructure and SRE
• When someone joins the Infrastructure team, they inherit permissions from both Infrastructure and Platform Engineering

This models real organizational structures without requiring you to duplicate permission grants across multiple teams.

Resource Sharing

Some resources — particularly credentials and secrets — use a sharing model in addition to the standard role hierarchy. A credential created at the organization level can be shared with specific environments, which controls where that credential can be used.

This is distinct from viewer/admin access. Sharing controls whether a resource can be referenced during deployments, while roles control who can view or modify the resource itself. See Connections: Environment Mappings for how this applies to credentials.

Context Switching

When a user belongs to multiple organizations, Planton tracks their active context — which organization they are currently operating in. List operations are context-aware: you only see resources in your active organization.

This prevents data leakage between organizations. A user with access to both Organization A and Organization B sees only Organization A's resources when their active context is set to A, regardless of their permissions in B.

Managing Access

Web Console

The web console provides a visual interface for managing access:

• Organization Settings > Members — Invite new members, assign initial roles, manage membership
• Organization Settings > Teams — Create teams, add members (individuals or other teams), view team permissions
• Organization Settings > Service Accounts — Create and manage machine identities with API key lifecycle
• Resource Detail > IAM — View and manage permissions on individual resources

CLI

The CLI provides commands for managing IAM policies programmatically:

# Grant a role on a resource
planton iam iam-policy add \
  --resource-kind organization \
  --resource-id org-acme \
  --principal-id ia-usr-alice \
  --role admin

# View who has access to a resource
planton iam iam-policy get \
  --resource-kind environment \
  --resource-id env-production

# View access grouped by role
planton iam iam-policy get \
  --resource-kind environment \
  --resource-id env-production \
  --group-by-role

# Include inherited permissions (from parent resources)
planton iam iam-policy get \
  --resource-kind environment \
  --resource-id env-production \
  --show-inherited

# Remove a role from a principal
planton iam iam-policy remove \
  --resource-kind organization \
  --resource-id org-acme \
  --principal-id ia-usr-alice \
  --role admin

# List all available roles
planton iam role list

The get command supports multiple output formats (--output-format table, json, or yaml) for integration with scripts and automation.

CLI Reference

Related Documentation

• Security Overview — Platform security model and architecture
• Audit Trails — Immutable change tracking
• Teams and Access — Member management, team structure, and billing
• Custom Domain — Your organization's console at its own address
• Connections — Credential management and environment authorization
• Runner Security Model — Credential isolation and mTLS