What is a Service User?

A Service User is a non-human account used to connect external systems and integrations to Custodia through the API. Instead of sharing an employee's login, each Service User has its own credentials (a client ID and client secret), its own permissions, and can be turned on or off independently. This lets you give an integration exactly the access it needs — and revoke it at any time — without affecting any person's account.

Availability

Creating Service Users is available to enterprise tenants by default. For benefit-card programs it can be enabled on request — contact your Custodia representative at support@custodia.ai. You need the Tech Admin role to create or manage Service Users.

How to Create a Service User

You can create a Service User in two ways: in the platform (recommended) or through the API.

Option 1: In the platform (recommended)

1. Log in to Custodia at https://my.custodia.ai with an account that has the Tech Admin role.
2. Navigate to the Service Users section.
3. Click Add, then provide a name (and an optional description) that identifies the integration, and select the scopes it needs.
4. Click Save. Custodia generates a Client ID and a Client Secret.
5. Copy both values and store them securely — the secret is shown only once (see Keeping your credentials secure).
6. Assign the roles the integration needs using the Roles option on the Service User.

Option 2: Via the API

Administrators can also create a Service User programmatically. First authenticate with a user that has the Tech Admin role (see the API Access Key Credentials Guide for how to obtain an access token), then call:

POST https://www.my.custodia.ai/api/System/createApplication
Authorization: {access_token}
Content-Type: application/json

{
  "name": "Payroll Sync",
  "description": "Integration for nightly payroll import",
  "scopes": ["DEFAULT"]
}

The response includes the new Client ID and Client Secret. For sandbox testing, use the base URL https://sandbox.custodia-tech.com instead.

To assign roles to the Service User afterward:

POST https://www.my.custodia.ai/api/RoleMapping
Authorization: {access_token}
Content-Type: application/json

{
  "principalId": "{service-user-id}",
  "principalType": "AppUser",
  "roleId": "{role-id}",
  "companyId": "{company-id}"
}

Using the Credentials

Your integration exchanges its Client ID and Client Secret for a short-lived access token using the OAuth 2.0 client_credentials grant, then includes that token on each API request. For the full authentication flow and code samples, see the API Access Key Credentials Guide.

Keeping Your Credentials Secure

• The Client Secret is shown only once. Custodia cannot retrieve or re-display it later, so save it in your secret manager or vault right away.
• Never share secrets by email or chat. Copy them directly into secure storage at creation time.
• Rotate by reissue. If a secret is lost or exposed, create a new Service User (or credential) and deactivate the old one — there is no way to reveal an existing secret.
• Use one Service User per integration and grant only the scopes and roles it needs, so you can revoke access to a single system without affecting others.

Key Details

Related Articles

• API Access Key Credentials Guide
• API User Management