nebius/api

nebius/api

Description: Nebius AI Cloud API

License: MIT

Stars: 16

Forks: 3

Open issues: 3

Created: 2024-09-09T14:21:51Z

Pushed: 2026-06-09T08:32:13Z

Default branch: main

Fork: no

Archived: no

README:

Nebius AI Cloud API

[![CI][ci-img]][ci-url] [![License][license-img]][license-url]

This repository contains the .proto files defining the gRPC API for Nebius AI Cloud services. These files describe the structure of requests and responses exchanged between your client application and Nebius services using Protocol Buffers.

Tools

While you can interact directly with the Nebius AI Cloud API, we recommend leveraging the following tools to simplify your development and operations:

• Nebius CLI
• Terraform Provider
• SDK for Go
• Python SDK

Using these tools can save time and reduce the complexity of managing authentication, constructing requests, and handling responses.

API Endpoints

Nebius AI Cloud gRPC services are available at endpoints formatted as {service-name}.api.nebius.cloud:443. A complete list of available services and their endpoints can be found [here](endpoints.md).

The {service-name} corresponds to the option (api_service_name) value defined in the respective .proto file. For example, requests to TokenExchangeService ([iam](nebius/iam/v1/token_exchange_service.proto)) should be sent to tokens.iam.api.nebius.cloud:443.

Special Case: the OperationService ([common](nebius/common/v1/operation_service.proto)) does not have a standalone endpoint. Instead, use the same endpoint as the service that initiated the operation. For instance, to check the status of an operation created by DiskService ([compute](nebius/compute/v1/disk_service.proto)), use compute.api.nebius.cloud:443.

Authentication

Nebius AI Cloud uses bearer token authentication. All requests must include an Authorization: Bearer header.

User Account Authentication

Prerequisites: Ensure you have installed and configured the nebius CLI as per the documentation.

Steps:

1. Run nebius iam get-access-token to retrieve your IAM access token. 1. Include this token in the Authorization header of your gRPC requests.

Example:

grpcurl -H "Authorization: Bearer $(nebius iam get-access-token)" \
cpl.iam.api.nebius.cloud:443 \
nebius.iam.v1.ProfileService/Get

Sample Response

{
"userProfile": {
"id": "useraccount-e00...",
"federationInfo": {
"federationUserAccountId": "...",
"federationId": "federation-e00..."
},
"attributes": {
...
}
}
}

Service Account Authentication

Prerequisites: You must have created a service account with the necessary credentials as outlined in the documentation.

Service account credentials cannot be directly used for authentication. Your service needs to obtain an IAM token using OAuth 2.0 with a compatible client library that implements RFC-8693 and JWT to generate a claim.

Steps: 1. Generate a JWT:

• Use the RS256 signing algorithm.
• Include the following claims:
• kid: Public Key ID of your service account.
• iss: Your service account ID.
• sub: Your service account ID.
• exp: Set a short expiration time (e.g., 5 minutes) as the token is only used for exchanging another token.
• Sign the JWT with the service account’s private key.

1. Exchange JWT for an IAM Token:

• Using gRPC: Call nebius.iam.v1.TokenExchangeService/Exchange on tokens.iam.api.nebius.cloud:443.
• Using HTTP: Send a POST request to https://auth.eu.nebius.com:443/oauth2/token/exchange.

1. Use the IAM Token from access_token from the response 1. Repeat the process before the IAM token expires (indicated by expires_in from the response).

Example using CLI tools and gRPC

SA_ID="serviceaccount-e00..."
KEY_ID="publickey-e00..."
PRIVATE_KEY_PATH="private_key.pem"

# https://github.com/mike-engel/jwt-cli
JWT=$(jwt encode \
--alg RS256 \
--kid $KEY_ID \
--iss $SA_ID \
--sub $SA_ID \
--exp="$(date --date="+5minutes" +%s 2>/dev/null || date -v+5M +%s)" \
--secret @${PRIVATE_KEY_PATH})

read -r -d '' REQUEST


Example using CLI tools and HTTP

SA_ID="serviceaccount-e00..." KEY_ID="publickey-e00..." PRIVATE_KEY_PATH="private_key.pem"

https://github.com/mike-engel/jwt-cli

JWT=$(jwt encode \ --alg RS256 \ --kid $KEY_ID \ --iss $SA_ID \ --sub $SA_ID \ --exp="$(date --date="+5minutes" +%s 2>/dev/null || date -v+5M +%s)" \ --secret @${PRIVATE_KEY_PATH})

RESPONSE=$(curl https://auth.eu.nebius.com:443/oauth2/token/exchange \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \ -d "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \ -d "subject_token=${JWT}" \ -d "subject_token_type=urn:ietf:params:oauth:token-type:jwt")

TOKEN=$(jq -r '.access_token'

Method Update and X-ResetMask Header

In Nebius AI Cloud API, the Update method is designed to perform a "full-replace" of resource fields rather than a "patch" operation. However, to maintain compatibility with clients of different versions, the server ensures that fields unknown to the client are not unintentionally modified. To achieve this, Nebius employs a mechanism called the Reset Mask.

> Note: Nebius' Reset Mask is distinct from Google's Field Mask.

Behavior

A field in a protobuf message is not transmitted over the wire if it has a default value (empty string, 0, false, or NULL). The server updates a resource field only if:

• The request contains a non-default value for that field, or
• The field is explicitly included in the mask provided in the X-ResetMask header.

For example, to detach (remove) secondary disks from a compute instance, you can use the following X-ResetMask:

grpcurl -H "Authorization: Bearer $TOKEN" \
-H "X-ResetMask: spec.secondary_disks" \
-d '{"metadata": {"id": "compute-instance-id"}}' \
compute.api.nebius.cloud:443 \
nebius.compute.v1.InstanceService/Update

The Nebius SDK for all supported languages manages the X-ResetMask header automatically.

Reset Mask Syntax

A reset mask is a comma-separated list of elements, where each element specifies one or more fields in a protobuf message.

Example:

a, b.c, d.e.12,…