Authentication in the Nebius AI Cloud API

​

Authentication for a user account

1. Install and configure the Nebius AI Cloud CLI.
2. Create an access token:
   nebius iam get-access-token
   
   An access token is valid for 12 hours. After it expires, create a new one.
3. Add the token to your API request. For example:
   grpcurl -H "Authorization: Bearer <access_token>" \
      cpl.iam.api.nebius.cloud:443 \
      nebius.iam.v1.ProfileService/Get
   

​

Authentication for a service account

​

Prepare a service account

1. Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
2. Create a service account if you haven’t already.
3. Add the service account to a group to grant it necessary permissions. In most cases, a group with the editor role should be enough; add the account to a group with the admin role only if you want to manage other accounts’ group memberships through the API. Learn more about groups and their permissions.

​

Prepare an authorized key

1. Create an authorized key:
   openssl genrsa -out private.pem 4096 && \
   openssl rsa -in private.pem -outform PEM -pubout -out public.pem
   
   This command creates the public.pem and private.pem key files in a local directory.
2. Upload the key to the service account profile:
   • Web console
   • CLI

   1. In the web console, go to Administration → IAM.
   2. Open the Service accounts tab.
   3. Open the page of the required service account.
   4. Click Upload authorized key.
   5. Click Attach file and then select public.pem.
   6. (Optional) Set an expiration date.
   7. Click Upload key.

   The key is displayed on the Authorized keys tab.

   nebius iam auth-public-key create \
     --account-service-account-id <service_account_ID> \
     --data "$(cat <path/to/public.pem>)" \
     --expires-at <date_and_time>
   

   The command contains the following parameters:

   • --account-service-account-id: Service account ID. To get it, run nebius iam service-account list or nebius iam service-account get-by-name —name <service_account_name>.
   • --data: Contents of the public.pem file created earlier.
   • --expires-at (optional): Expiration date of the authorized key.

   Output example

   metadata:
      created_at: "2025-08-22T09:37:07.023669Z"
      id: publickey-***
      parent_id: project-***
   spec:
      account:
         service_account:
         id: serviceaccount-***
      data: |
         -----BEGIN PUBLIC KEY-----
         ...
         -----END PUBLIC KEY-----
      expires_at: "2025-12-31T02:30:59Z"
   status:
      algorithm: RSA
      fingerprint: a4c4***
      key_size: 4096
      state: ACTIVE
   
3. Copy and save the account ID and the authorized key ID. You need them for the JWT.

​

Create a JWT

1. Install jwt-cli, the CLI for JWT management.
2. Create the JWT:
   jwt encode \
      --alg RS256 \
      --kid <authorized_key_ID> \
      --iss <service_account_ID> \
      --sub <service_account_ID> \
      --exp="$(date --date="+5minutes" +%s 2>/dev/null || date -v+5M +%s)" \
      --secret @<path_to_private.pem>
   
   The command returns the JWT as a string. Use this value as subjectToken in the token exchange request. In the command, specify the copied authorized key ID and the service account ID. Also, specify the current path to the private.pem file created earlier. The JWT is based on the RS256 signing algorithm and expires five minutes after its creation. The lifetime is short because the JWT is only used to create an access token.

​

Get an access token

1. To exchange the JWT for an access token, send the following API request:
   grpcurl -d '{
                  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
                  "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
                  "subjectToken": "<JWT>",
                  "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt"
               }' \
      tokens.iam.api.nebius.cloud:443 \
      nebius.iam.v1.TokenExchangeService/Exchange
   
   Specify the JWT in the request. The output is the following:
   {
      "accessToken": "<access_token>",
      "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
      "tokenType": "Bearer",
      "expiresIn": "43200"
   }
   
   The access token expires 12 hours after its creation. The expiresIn value from the output is specified in seconds.
2. Add the token to your API request. For example:
   grpcurl -H "Authorization: Bearer <access_token>" \
      cpl.iam.api.nebius.cloud:443 \
      nebius.iam.v1.ProfileService/Get