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.

Troubleshooting​

User not found when calling the API with a service principal token​

This error means the API call could not resolve the identity behind the token. Check the following in order:

  1. Default catalog is set on the project. Some API operations require a default catalog to be configured under Project Settings → Catalogs. Without one, calls that don't specify a catalog explicitly will fail with User not found.
  2. The service principal is invited to the target project. Account-level creation is not enough — a project admin must invite the SP from Project Settings → Users & Access.
  3. The service principal has the required role on the resource. Membership alone does not grant access to individual Flows, Jobs, Lakes, or Clusters — see Permissions.
  4. The token was generated for the correct service principal. If you rotated or recreated the SP, old tokens are invalid even if the SP name is unchanged.

ALREADY_EXISTS from CREATE JOB when the job does not appear in the console​

The console list is scoped to projects you can see. A service principal can create a Job in a project where you have no access; the Job exists, but you can't view it. Either grant your user access to that project, or use the service principal token to enumerate Jobs via SHOW JOBS.

Cluster not found from CREATE JOB despite the cluster being visible to your user​

API calls executed with a service principal token are evaluated against the service principal's permissions, not yours. If the SP lacks a cluster role, the cluster appears not to exist. Grant the SP the required role on the cluster (or use the cluster's UUID, which can sometimes succeed where the name lookup fails — but the permission grant is the durable fix).

API token expired and you need a long-lived credential​

API tokens have a maximum lifetime — Onehouse does not currently issue tokens that live longer than the standard window. For long-lived automation (CI, Airflow, scheduled jobs), use a service principal and rotate its tokens on a schedule. See Generate API tokens with a service principal.