Configuring Service Accounts and User Tokens in Nexus Repository Cloud
This page describes how to configure service account authentication in Nexus Repository Cloud. Use Service Account Tokens as the recommended method for automation because they let service accounts authenticate to repository clients without using a personal user account. As an alternative, you can use a dedicated Cloud user account with a user token for user-based service account workflows.
Internal and External Role Management
The Nexus Repository Cloud user role management API manages Nexus-internal role mappings only.
The API can return external roles for visibility, but external roles are read-only and must be managed through the identity provider.
Prerequisites
Administrator access to the Nexus Repository Cloud tenant.
A shared or dedicated email address for each service account.
A person available to complete the initial 2FA enrollment on behalf of the service account.
The Nexus-internal role IDs required by the service account.
For API-based user invitations and role assignment, an API caller with the required permissions:
nexus:users:createto invite users,nexus:users:readto view role assignments, andnexus:users:updateto update role assignments.
Step 1: Add a User for the Service Account
Service accounts on Nexus Repository Cloud are provisioned by inviting a user through the Nexus Repository Cloud UI or the invite user API.
Add a User via the UI
In Nexus Repository Cloud, navigate to Settings → Security → Users.
Select Invite Users.
Enter the service account email address and name.
Click Invite User. A confirmation email is sent to the service account email address.
Add a User via the API
For API-based provisioning in Nexus Repository Cloud, use the invite user API. This sends an invitation email to the service account email address.
curl -u <admin-user>:<admin-password-or-token> -X POST \
-H 'Content-Type: application/json' \
'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/invite' \
-d '{ "firstName": "Service", "lastName": "Account", "email": "[email protected]" }'The API caller must have the nexus:users:create permission.
Example response:
{ "firstName": "Service", "lastName": "Account", "email": "[email protected]" }External Users
If the service account is managed through an external identity provider, create the account in the identity provider first. Then ensure the user is available to Nexus Repository Cloud before assigning Nexus-internal roles.
Step 2: Initial Login and 2FA Enrollment
A human must complete this step on behalf of the service account:
Access the invitation email and follow the link to verify the email address.
Enter a password for the service account.
Complete 2FA enrollment using the required authenticator for your organization.
Log in to the Nexus Repository Cloud tenant at least once to confirm the account is active.
2FA Recovery Planning
Before using a service account in automation, document how your team will recover access if the person who enrolled 2FA is unavailable. Follow your organization's credential management policy.
Step 3: Assign the Appropriate Role
Before generating and using a service account token, ensure the service account has the correct Nexus-internal roles for its intended purpose. Apply the principle of least privilege.
For service accounts used in repository automation, assign only the repository permissions required by the automation. For example, a read-only automation account may need repository browse and read privileges, while a publishing account may also need add or edit privileges for the target repositories.
Assign a Role via the UI
In Nexus Repository Cloud, navigate to Settings → Security → Users.
Search for and select the service account user.
Update the user's assigned roles.
Save the user.
See Roles for more information.
Role Assignments
In Nexus Repository Cloud, users authenticate through Auth0. You can assign Nexus-internal roles to users from the Users view.
External group-based access is managed through your identity provider and the configured role mappings.
Assign a Role via the API
For automation or bulk provisioning, use the Nexus Repository Cloud user role management API. See Security Management API for the complete API reference.
To review the user's current Nexus-internal and external roles:
curl -u <admin-user>:<admin-password-or-token> -X GET \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles'
To replace the user's complete set of Nexus-internal roles:
curl -u <admin-user>:<admin-password-or-token> -X PUT \ -H 'Content-Type: application/json' \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles' \ -d '{ "roles": ["nx-repository-view-*-*-browse", "nx-repository-view-*-*-read"] }'To add roles without replacing existing Nexus-internal role assignments:
curl -u <admin-user>:<admin-password-or-token> -X PUT \ -H 'Content-Type: application/json' \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles/add' \ -d '{ "roles": ["nx-repository-view-*-*-add"] }'To remove roles without replacing existing Nexus-internal role assignments:
curl -u <admin-user>:<admin-password-or-token> -X PUT \ -H 'Content-Type: application/json' \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles/remove' \ -d '{ "roles": ["nx-admin"] }'URL Encode User IDs
If the userId contains special characters, such as @ in an email address, URL encode the value before sending the request. For example, use svc-nexus-ci%40example.com for [email protected].
Replacement Behavior
PUT /v1/security/users/{userId}/roles replaces the user's complete Nexus-internal role set. Use PUT /v1/security/users/{userId}/roles/add or PUT /v1/security/users/{userId}/roles/remove when you want to preserve existing Nexus-internal role assignments.
Step 4: Generate a User Token
Once the service account has logged in and has the appropriate role assignments, generate a user token for use in automation.
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 for configuration details.
Generate User Token via the UI
 |  |
Nexus One UI | Classic UI |
Log in to Nexus Repository Cloud as the service account user.
Select the profile icon at the top right.
Select User Token.
Select the Generate Token button (if you’re using the Classic UI, select the Access User Token button instead).
Save the token credentials immediately and store them securely.
Generate User Token via the API
Use the Nexus Repository user token API to generate a token programmatically after the service account has completed initial login and 2FA enrollment.
curl -u [email protected]:<service-account-password> -X POST \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/user-tokens/current'
Token Storage
Store generated token credentials in an approved secrets manager. Do not commit service account passwords or generated token credentials to source control.
Step 5: Use the Token for Repository Automation
Use the generated user token credentials in build tools, package managers, CI/CD jobs, or scripts that need to authenticate to Nexus Repository Cloud.
Example API call using token credentials:
curl -u <user-token-code>:<user-token-passcode> \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/status'
Confirm that the service account can perform only the actions required by its automation.
Step 6: Verify and Maintain Role Assignments
After the service account is configured, periodically verify that the assigned roles still match the automation requirements.
Verify Roles via the UI
In Nexus Repository Cloud, navigate to Settings → Security → Users.
Search for and select the service account user.
Review the assigned roles.
Remove roles that are no longer required.
Verify Roles via the API
Use the Get User Roles endpoint to review Nexus-internal and external roles. See Security Management API for response details and error handling.
curl -u <admin-user>:<admin-password-or-token> -X GET \ 'https://<your-nexus-repository-cloud-url>/service/rest/v1/security/users/svc-nexus-ci%40example.com/roles'
Example response:
{ "userId": "[email protected]", "roles": ["nx-repository-view-*-*-browse", "nx-repository-view-*-*-read"], "externalRoles": ["Sonatype Platform - Repository Users"] }The roles field contains Nexus-internal role assignments managed by Nexus Repository Cloud. The externalRoles field contains external or IdP-managed roles and is read-only through this API.