Skip to main content

Service Principals

Service principals are non-human identities that allow you to grant permissions for API access to Onehouse without tying credentials to a specific user.

How service principals work​

Service principal can be granted roles and privileges in Onehouse. Then, users with access to the service principal can create API tokens that leverage the service principal's permissions.

Service principals are scoped to the account-level, so they can receive permissions across multiple projects, similar to a user or a group.

Service principal roles​

Users may have the following roles on a service principal:

  • Service Principal User: Can create API tokens with the service principal.
  • Service Principal Manager: Can edit the service principal (change name or editing roles), delete the service principal, and create/revoke API tokens.

See the permissions docs for full details on service principal permissions.

Create a service principal​

To create a service principal, you must be an account admin.

  1. Open your account console.
  2. Navigate to Settings > User Management.
  3. Open the Service Principals tab and create a service principal.

Invite users to a service principal​

  1. Open your service principal in the account console.
  2. Open the 'Permissions' tab and click the 'Grant Access' button.
  3. Add users to access the service principal.

Grant permissions to a service principal​

You can add permissions to a service principal in the same way that you would to a user.

  1. First, a project admin must add the service principal to a project.
    1. Open the project.
    2. Open Settings → Users & Access.
    3. Click 'invite user' and add the service principal.
  2. Assign roles and privileges to the service principal within the project.

After you grant permissions to a service principal, anyone with a token for the service principal can use those permissions via the Onehouse APIs.

Generate API tokens with a service principal​

  1. Open your service principal in the account console.
  2. Open the 'Tokens' tab and click the 'Generate token' button.
  3. Name your token and generate it. Be sure to save the secret key.
  4. Use this token to submit requests to the Onehouse API.

Additional usage notes​

  • When a user loses access to a service principal, tokens they created will still be valid. Account admins or service principal managers should rotate tokens regularly.
  • Users with management access to a resource (e.g., a Cluster) can grant roles to a service principal for that resource, even if they are not a user of the service principal themselves.