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

​

Steps

​

Prepare a service account

1. Create a service account if you have not already.
2. 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 certificates in a local directory.
2. Upload the key to the service account profile:
   • Web console
   • CLI

   1. In the sidebar, 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. To attach the public.pem file, 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. From the service account page, copy and save the account ID and the authorized key ID. You need them for the JSON Web Token.

​

Create a JSON Web Token

1. Install jwt-cli, the CLI for the JSON Web Token management.
2. Create the JSON Web Token:
   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>
   
   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 JSON Web Token is based on the RS256 signing algorithm. The token expires five minutes after its creation. The lifetime is short because the JSON Web Token is only used to create an access token.

​

Get an access token

1. To exchange the JSON Web Token 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": "<JSON_Web_Token>",
                  "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt"
               }' \
      tokens.iam.api.nebius.cloud:443 \
      nebius.iam.v1.TokenExchangeService/Exchange
   
   Specify the JSON Web Token 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