Service Accounts

Service Accounts are non-human identities that provide programmatic access to the Phase platform. They are used by applications, CI/CD pipelines, automation scripts, and any other machine-to-machine workflow that needs to interact with secrets.

How Service Accounts Work

Service Accounts share many properties with User accounts. Each Service Account has:

• A unique cryptographic keyring — Just like Users, each Service Account has its own encryption keys. This means access to secrets is cryptographically enforced, not just permission-based.
• A role — Determines the permissions the account has. By default, new Service Accounts are assigned the managed Service role, which provides full access to secrets at the App level with minimal organisation-level permissions.
• Scoped access — Service Accounts must be explicitly added to Apps and granted access to specific Environments before they can access any secrets.
• Tokens — Authentication credentials that the Service Account uses to interact with Phase via the CLI, SDKs, or API.

Org-level vs Team-owned Service Accounts

Service Accounts exist in two categories:

• Org-level — The default. Created at the organisation level and visible to any member with the ServiceAccounts read permission. Available on all plans.
• Team-owned — Created within a Team. The account is automatically added as a team member and inherits the team's App and Environment access. It is visible only to team members and users with global access (Owner and Admin).

A team-owned Service Account's lifecycle is tied to its team: deleting the team deletes the account and revokes its tokens. Ownership cannot be changed after creation — a team-owned account cannot be moved to another team or converted to an org-level account.

See Team-owned service accounts for creation and management details.

Service Accounts vs Users

Roles

Service Accounts follow the same RBAC system as Users. They can be assigned any managed role or custom role. The default Service role is designed specifically for programmatic access:

You can assign a different role if the Service Account needs broader or more restricted permissions.

KMS Modes

Each Service Account's keyring can operate in one of two KMS modes, which determine who can create and manage tokens for the account.

Client-side KMS

The default mode for org-level Service Accounts. The Service Account's keyring is only accessible to designated users (called Service Account Handlers) who have the required ServiceAccountTokens permissions. The keyring is encrypted with each handler's keys, so only they can create and manage tokens.

This is the most secure mode — the Phase server never has access to the Service Account's keyring.

Server-side KMS

Optionally, you can grant the Phase backend access to the Service Account's keyring. This allows the server to create and manage tokens on behalf of the Service Account. Server-side KMS is required for:

• External Identities — Allowing external identity providers (AWS IAM, and Azure Managed Identities or Service Principals) to authenticate as this Service Account
• Automated token management without requiring a human handler

Team-owned Service Accounts always use Server-side KMS. It is enabled automatically at creation, so any team member with the appropriate ServiceAccountTokens permissions can generate tokens without being a designated handler.

Tokens

Service Accounts authenticate with Phase using tokens. Tokens are bound to the Service Account's role and access scope. They can be used with:

• CLI — phase auth with a service token
• SDKs — Pass the token when initialising the Phase client
• API — Include the token in API request headers

For details on creating and managing tokens, see Tokens.

Network Access Policies

Service Accounts can have Network Access Policies applied to restrict which IP addresses or CIDR ranges can authenticate using the account's tokens. This adds an additional layer of security for production service accounts.

Managing Service Accounts

Service Accounts can be created and managed through the Phase Console. From the Console you can:

• Create new accounts with a chosen name and role
• Create team-owned accounts from within a Team
• Update account names and roles
• Switch between Client-side and Server-side KMS
• Add accounts to Apps with specific Environment access
• Create and revoke tokens
• Apply Network Access Policies
• Delete accounts