# Configuring Service Accounts and User Tokens - IQ Cloud

This page describes the recommended process for creating and managing user tokens for service accounts on Sonatype IQ Cloud, specifically when using the Sonatype Identity Provider (IdP).

**Important**  
In IQ Server, a user token can only be generated by the user authenticating as themselves. System administrators cannot generate a token on behalf of another user. This is a security constraint that applies to all realm types (Internal, SAML, LDAP) to prevent impersonation and ensure that tokens are only issued to authenticated users. See [User Token REST API](https://help.sonatype.com/en/user-token-rest-api.html "User Token REST API").

## Prerequisites

- System Administrator access to the Sonatype Lifecycle Cloud tenant.
- A shared or dedicated email address for each service account.
- A person available to complete the initial MFA enrollment on behalf of the service account.

## Step 1: Add a User for the Service Account

Service accounts on Lifecycle Cloud are provisioned by inviting a user through the Lifecycle UI or the API.

### Add a User via the UI

1. In Sonatype Lifecycle Cloud, navigate to _System Preferences_ (gear icon at the top right) → _Users_.
2. Select _Invite User_ and fill in the user details (email, first name, last name).
3. Click _Save_. An email with setup instructions is sent to the provided email address.

### Add a User via the API

For large-scale provisioning, the [User REST API](https://help.sonatype.com/en/user-rest-api.html "User REST API") can create service accounts programmatically:

```
curl -u admin:admin123 -X POST -H 'Content-Type: application/json' \  'https://<your-tenant>.sonatype.app/platform/api/v2/users' \  -d '{    "username": "svc-account-01",    "password": "secret",    "firstName": "Service",    "lastName": "Account01",    "email": "svc-account-01@example.com"  }'
```

**Note**  
Users created via the API are created as internal users, not as users from your configured identity provider.

## Step 2: Initial Login and MFA Enrollment

A human must complete this step on behalf of the service account:

1. Access the invitation email and follow the link to set a password.
2. Complete MFA enrollment using a supported authenticator (e.g., Google Authenticator, Microsoft Authenticator). See [Authentication with Sonatype Cloud](https://help.sonatype.com/en/authentication-with-sonatype-cloud.html "Authentication with Sonatype Cloud").
3. Log in to the Lifecycle Cloud tenant at least once to establish the account session.

**Tip**  
Multiple devices can scan the same QR code during MFA setup, which allows multiple team members to access the service account if needed.

After initial login, assign the appropriate IQ role to the service account through the administrator UI or role management APIs.

## Step 3: Assign the Appropriate Role

Before generating a user token, ensure the service account has the correct role for its intended purpose. For service accounts used in CI/CD scanning automation, the principle of least privilege applies.

Recommended role for CI/CD application scans: `Application Evaluator`. This role grants access to evaluate applications and receive policy violation summary results within the CI workflow. It limits service accounts to evaluation workflows and avoids broad access to application data or policy results. See [Role Management](https://help.sonatype.com/en/role-management.html "Role Management").

### Assign a Role via the UI

1. In Sonatype Lifecycle Cloud, navigate to _Orgs & Policies_ and select the target organization or application.
2. Click _Access_ → _Add a Role_.
3. Select the appropriate role and search for the service account username.
4. Click _Create_ to confirm.

### Assign a Role via the REST API

For bulk provisioning, use the Authorization Configuration REST API:

At the application level:

```
curl -u admin:admin123 -X PUT \  'https://<your-tenant>.sonatype.app/platform/api/v2/roleMemberships/application/{applicationId}/role/{roleId}/user/{userName}'
```

At the organization level:

```
curl -u admin:admin123 -X PUT \  'https://<your-tenant>.sonatype.app/platform/api/v2/roleMemberships/organization/{organizationId}/role/{roleId}/user/{userName}'
```

## Step 4: Generate a User Token

Once the service account has logged in at least once, a user token can be generated either via the UI or the REST API.

**User Token Expiration**  
For improved security, enable user token expiration if it is not already enabled. User token expiration applies to existing and newly generated tokens. See [User Tokens](https://help.sonatype.com/en/iq-server-user-tokens.html "User Tokens") for configuration details.

### Generate User Token via the UI

1. Log in as the service account user.
2. Click the Profile icon (top-right corner) → _Manage User Token_.
3. Click _Generate User Token_ and save the credentials immediately; the `userCode` and `passCode` are only shown once and cannot be retrieved afterwards.

See [User Tokens](https://help.sonatype.com/en/user-tokens.html "User Tokens").

### Generate User Token via the REST API

After the initial UI login, the service account can generate its own token programmatically using basic authentication with its own credentials:

```
curl -u svc-account-01:my-secret -X POST \  https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/currentUser
```

Example response:

```
{  "userCode": "NFWIevo8",  "passCode": "wv5XosXBU5EBv1OfT31POJ0MgGGbHgbtIRYxq9k4GRgg"}
```

Store this response securely. The `passCode` cannot be retrieved after this response is returned.

See [User Token REST API](https://help.sonatype.com/en/user-token-rest-api.html "User Token REST API").

### Using the Token for API / CI Calls

```
curl -u NFWIevo8:wv5XosXBU5EBv1OfT31POJ0MgGGbHgbtIRYxq9k4GRgg \  https://<your-tenant>.sonatype.app/platform/api/v2/organizations
```

## Step 5: Administrator Token Management

While administrators cannot create tokens for other users, they have the following management capabilities:

**Query all user tokens (by realm)**

```
curl -u admin:admin123 -X GET \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens?realm=Internal'
```

**Query token for a specific username**

```
curl -u admin:admin123 -X GET \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/svc-account-01?realm=Internal'
```

The response includes only the `userCode` (not the `passCode`) and the associated username and realm.

**Delete a user token by user code**

```
curl -u admin:admin123 -X DELETE \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/userCode/NFWIevo8'
```

Returns 204 No Content on success.

**Purge obsolete tokens**

```
curl -u admin:admin123 -X DELETE \  'https://<your-tenant>.sonatype.app/platform/api/v2/userTokens/purge'
```

**Configure token expiration (System Administrators only)**

```
# Set expiration to 90 days
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" \  -d '{"userTokenDefaultExpirationDays": 90}' \  https://<your-tenant>.sonatype.app/platform/api/v
```