> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication in the Nebius AI Cloud API

For authentication, use an [access token](../iam/authorization/access-tokens). Include it in the HTTP header `Authorization: Bearer <access_token>`.

The authentication process differs for a [user account and a service account](../iam/overview#accounts-and-members).

## Authentication for a user account

1. [Install](/cli/install) and [configure](/cli/configure) the Nebius AI Cloud CLI.

2. Create an access token:

   ```bash theme={null}
   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:

   ```bash theme={null}
   grpcurl -H "Authorization: Bearer <access_token>" \
      cpl.iam.api.nebius.cloud:443 \
      nebius.iam.v1.ProfileService/Get
   ```

## Authentication for a service account

To authenticate a service account, create an [authorized key](../iam/service-accounts/authorized-keys) for it and then convert this key into an access token by using a [JSON Web Token](https://www.jwt.io/introduction). Next, use the obtained access token for the authentication.

### Steps

#### Prepare a service account

1. [Create a service account](../iam/service-accounts/manage) if you have not already.
2. [Add the service account to a group](../iam/authorization/groups/members) 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](../iam/authorization/groups) and their [permissions](../iam/authorization/roles).

#### Prepare an authorized key

1. Create an authorized key:

   ```bash theme={null}
   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:

   <Tabs group="interfaces">
     <Tab title="Web console">
       1. In the [web console](https://console.nebius.com), go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/sidebar/administration.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e6411dc023fd6972922c0a12a59ccf21" width="16" height="16" data-path="_assets/sidebar/administration.svg" /> **Administration** → **IAM**.
       2. Open the **Service accounts** tab.
       3. Open the page of the required service account.
       4. Click <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/arrow-up-to-line.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=5ed27f4ff211ee66d1ee185f2af2955e" width="16" height="16" data-path="_assets/arrow-up-to-line.svg" /> **Upload authorized key**.
       5. Click <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/scraper.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=ff78334f556ea2b3be40db941b89c608" width="16" height="16" data-path="_assets/scraper.svg" /> **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.
     </Tab>

     <Tab title="CLI">
       ```bash theme={null}
       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 <code>nebius iam service-account list</code> or <code>nebius iam service-account get-by-name --name \<service\_account\_name></code>.
       * `--data`: Contents of the `public.pem` file created earlier.
       * `--expires-at` (optional): Expiration date of the authorized key.

       <Accordion title="Output example">
         ```yaml theme={null}
         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
         ```
       </Accordion>
     </Tab>
   </Tabs>

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](https://github.com/mike-engel/jwt-cli?tab=readme-ov-file#installation), the CLI for the JSON Web Token management.
2. Create the JSON Web Token:

   ```bash theme={null}
   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:

   ```bash theme={null}
   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:

   ```json theme={null}
   {
      "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:

   ```bash theme={null}
   grpcurl -H "Authorization: Bearer <access_token>" \
      cpl.iam.api.nebius.cloud:443 \
      nebius.iam.v1.ProfileService/Get
   ```