Getting Started with Service Identities
Overview
In this tutorial you’ll create a Service Identity, grant it access the same way you would a user, generate a token, and use that token to authenticate and check out a profile from the CLI. By the end you’ll have a working non-human identity that automation can use for just-in-time access.
What you’ll learn:
- What a Service Identity is and how it differs from a User
- How to create one and assign access via a tag and profile
- How to generate a token and authenticate with PyBritive or the API
Before You Begin
- A Britive tenant with administrator access (to create the identity and assign access)
- An existing access profile you can grant the identity (or permission to create one)
- PyBritive installed if you want to test from the CLI
A service identity token is a credential. Store it in a secret manager or CI/CD secret store — never in source control or plain environment files. Create one identity per workload so you can revoke it without affecting others.
Service Identity vs. User
| User | Service Identity | |
|---|---|---|
| Represents | A person | A machine / workload / automation |
| Authenticates with | Interactive login (SSO, MFA) | Token (programmatic) |
| Appears in audit as | actor.type = User | actor.type = ServiceIdentity |
| Gets access via | Tags, profiles, policies | Tags, profiles, policies (same model) |
Create the Service Identity
Open Service Identities
In the Britive console, go to Identity Management → Service Identities → Add Service Identity.
Name it for its workload
Give it a clear, workload-specific name and description.
| Field | Example |
|---|---|
| Name | ci-deploy-bot |
| Description | GitHub Actions deploy pipeline — prod |
Save the identity.
Grant Access
Service identities get access through the same tag → profile → policy model as users. Using a tag keeps it scalable.
Add the identity to a tag
Go to Identity Management → Tags, open (or create) a tag such as automation, and add ci-deploy-bot as a member.
Make sure a profile grants that tag access
Open the access profile the workload needs. Under its policy, confirm the automation tag is a member. If not, add it.
For automation that runs unattended, avoid approval or MFA step-up conditions on the profile policy used by the service identity — those require human interaction the workload can’t provide.
Generate a Token
Create the token
On the service identity, open Tokens → Generate Token. Set an expiration appropriate for the workload.
Store it securely
Copy the token once and store it in your secret manager or CI/CD secret (e.g. a GitHub Actions secret). You won’t be able to view it again.
Authenticate and Check Out
Provide the token via the standard environment variable, then check out a profile:
export BRITIVE_API_TOKEN="<service-identity-token>"
export BRITIVE_TENANT="your-tenant"
# list what this identity can access
pybritive ls profiles
# check out a profile (short-lived credentials)
pybritive checkout "<profile-alias>"BRITIVE_TENANT takes just the subdomain — see Finding Your Tenant Name.
Verify
Confirm the checkout succeeded
The CLI returns short-lived credentials for the profile. The workload can now use them.
Confirm attribution in the audit log
In the Britive console audit log, the checkout appears with actor.type = ServiceIdentity and the identity’s name — proof the automation acted as itself, not a shared human account.
Next Steps
- Service Identities series overview — what’s coming next
- SIEM Recommended Alerts — monitor service-identity and token activity
- PyBritive CLI tutorials