API

This page provides a brief overview of the NVCF API. All API endpoints are served through your gateway. See gateway-routing for details on configuring your gateway domain and DNS.

OpenAPI Specification

This page does not cover all endpoints.

Please refer to the OpenAPI Spec for the latest API information.

The NVCF API is divided into the following sets of APIs:

API Versioning

All API endpoints include versioning in the path prefix.

$
/v2/nvcf

Authorization

Self-hosted NVCF uses three bearer credential types:

All three credential types are sent as bearer credentials:

$
Authorization: Bearer <credential>

Use the CLI for normal credential management:

$
nvcf-cli init
$
nvcf-cli api-key generate

nvcf-cli init calls the API Keys admin endpoint and mints the JWT used as NVCF_TOKEN. The CLI saves the token in ~/.nvcf-cli.state for the default configuration and reads it automatically on later commands. Export it only when you are making direct API calls or using tooling that reads environment variables:

$
export NVCF_TOKEN=$(jq -r .token ~/.nvcf-cli.state)

The default self-hosted admin issuer role gives this token the following scopes:

• register_function
• list_functions
• list_functions_details
• deploy_function
• update_function
• update_secrets
• delete_function
• manage_telemetries
• manage_registry_credentials
• cluster-management

The function API key (NVCF_API_KEY) is created with these default scopes:

• invoke_function
• list_functions
• queue_details
• list_functions_details

The task API key (NVCF_NVCT_API_KEY) is created with these default scopes:

• launch_task
• list_tasks
• task_details
• cancel_task
• delete_task
• list_events
• list_results
• update_secrets

NVCF API authorization is scope-based. For the NVCF API endpoints below, either NVCF_TOKEN or NVCF_API_KEY can be used if that bearer includes the required scope. The CLI prefers NVCF_API_KEY for read, invoke, and queue commands. It prefers NVCF_TOKEN for management commands when both credentials are configured.

Pass --scopes when you need to narrow a key or create a key with management scopes for testing.

Scope reference

The OpenAPI spec describes the permission checked for each endpoint. “Accepted bearer” means which saved CLI credential type can be sent as Authorization: Bearer <credential> when it includes the listed scope.

Self-hosted cluster management uses SIS endpoints from the Spot API. In self-hosted CLI workflows, use NVCF_TOKEN with the cluster-management scope for these endpoints.

Task management uses NVCT endpoints served through your gateway. All task endpoints require NVCF_NVCT_API_KEY with the listed scope.

Direct API key creation

The CLI calls the API Keys service for you. If you need to call it directly, send NVCF_TOKEN, then set expires_at and the scopes array explicitly.

$
GATEWAY_ADDR=<your-gateway-address>
$
NVCF_TOKEN=<token-from-nvcf-cli-init>
$
EXPIRES_AT=$(date -u -v+1d '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u -d '+1 day' '+%Y-%m-%dT%H:%M:%SZ')
$
SERVICE_ID="nvidia-cloud-functions-ncp-service-id-aketm"
$
$
curl -s -X POST "http://${GATEWAY_ADDR}/v1/keys" \
>
  -H "Host: api-keys.${GATEWAY_ADDR}" \
>
  -H "Content-Type: application/json" \
>
  -H "Authorization: Bearer ${NVCF_TOKEN}" \
>
  -H "Key-Issuer-Service: nvcf-api" \
>
  -H "Key-Issuer-Id: ${SERVICE_ID}" \
>
  -H "Key-Owner-Id: test@nvcf-api.local" \
>
  -d '{
>
    "description": "invocation key",
>
    "expires_at": "'"${EXPIRES_AT}"'",
>
    "authorizations": {
>
      "policies": [{
>
        "aud": "'"${SERVICE_ID}"'",
>
        "auds": ["'"${SERVICE_ID}"'"],
>
        "product": "nv-cloud-functions",
>
        "resources": [
>
          {"id": "*", "type": "account-functions"},
>
          {"id": "*", "type": "authorized-functions"}
>
        ],
>
        "scopes": ["invoke_function", "list_functions", "queue_details", "list_functions_details"]
>
      }]
>
    },
>
    "audience_service_ids": ["'"${SERVICE_ID}"'"]
>
  }' | jq .