Access Control

Access Control is the foundation of AgentBase. It covers two closely related concerns: Agent Identity (registering your agent on the platform) and Auth & Secrets (storing and injecting credentials your agent needs to call external services).

Portal: https://aiplatform.console.vngcloud.vn/access-control
API Base URL: https://agentbase.api.vngcloud.vn/identity/api/v1

Core Concepts

What Is an Identity?

In AgentBase, an Identity is a named, platform-managed record that uniquely represents your agent within the organization. Think of it as the agent's "account" — the foundation on which everything else is built. An identity must exist before a Runtime can be created for that agent, and before any auth credentials can be retrieved.

An identity has:

A unique name (scoped to the organization)
An optional description and metadata
A list of associated auth configurations (the credentials this identity can retrieve)

Identity naming rules:

3–50 characters
Alphanumeric, underscore _, and hyphen - only (^[a-zA-Z0-9_-]+$)
Must be unique within the organization

Identity vs. Runtime

An Identity is persistent and environment-agnostic. A Runtime is tied to a specific container image and compute configuration. Multiple runtimes (for example, staging and production) can share the same identity.

Identity: my-order-agent (persistent)
     │
     ├─── Runtime: my-order-agent-staging  (environment-specific)
     └─── Runtime: my-order-agent-prod     (environment-specific)

Outbound Authentication

When your agent calls external services (OpenAI, Google, Slack, internal APIs), it needs credentials. AgentBase's Auth system lets you store these credentials centrally and have them automatically delivered to your agent at runtime — without hardcoding them.

The auth system supports three credential types:

Static API Key — A fixed string (such as an API key) associated with an identity. Use when the external service issues a long-lived API key and you want centralized management.
Delegated API Key — A credential that is scoped and potentially short-lived, useful for multi-tenant scenarios where different agents should get different scoped keys.
OAuth2 Provider — For services that use OAuth2 (Google, Slack, and others). AgentBase stores the client credentials and refresh token, and handles token refresh automatically.

Provider Type

Use Case

Storage

Static API Key

Long-lived keys (OpenAI, AIP, etc.)

Encrypted at rest

Delegated API Key

End-user federated keys

Per-user, federated

OAuth2

Third-party services (Google, GitHub, Slack, etc.)

Encrypted, auto-refreshed

Security model: Credentials are stored in HashiCorp Vault.

Agent Identity

Portal

Create an Identity

Open https://aiplatform.console.vngcloud.vn/access-control
Click "Create Identity"
Fill in:
- Name (required): e.g., my-order-agent — lowercase, alphanumeric and hyphens
- Description (optional): e.g., Handles order inquiries
- Allowed Return URLs (optional): OAuth2 callback URLs for this identity
Click Create
The new identity appears in the list with status ACTIVE

List Identities

Open https://aiplatform.console.vngcloud.vn/access-control
All identities are shown in a paginated list

Get Identity Details

Open https://aiplatform.console.vngcloud.vn/access-control
Click on the identity name

Update an Identity

Open https://aiplatform.console.vngcloud.vn/access-control
Click on the identity name → "Edit"
Update description or allowed return URLs → Save

Delete an Identity

Warning: Deleting an identity is irreversible. Stop all associated runtimes and remove all auth configurations before deleting.

Open https://aiplatform.console.vngcloud.vn/access-control
Find the identity → Delete → confirm

RESTful API

Prerequisite: All API examples below use $TOKEN — an IAM bearer token. See Configure Authentication for how to obtain it.

Create an Identity

curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/agent-identities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-order-agent",
    "description": "Handles order inquiries via Salesforce",
    "allowedReturnUrls": []
  }' | jq .

Example response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-order-agent",
  "description": "Handles order inquiries via Salesforce",
  "allowedReturnUrls": [],
  "createdAt": "2026-03-18T09:00:00Z",
  "updatedAt": "2026-03-18T09:00:00Z"
}

Error: 409 Conflict — name already exists. Choose a different name or use the existing identity.

List Identities

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/agent-identities?page=0&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response shape:

{
  "content": [...],
  "totalElements": 3,
  "totalPages": 1,
  "size": 20,
  "number": 0
}

Get Identity Details

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/agent-identities/my-order-agent" \
  -H "Authorization: Bearer $TOKEN" | jq .

Update an Identity

You can update the description and allowed return URLs. The name and ID are immutable.

curl -s -X PUT "https://agentbase.api.vngcloud.vn/identity/api/v1/agent-identities/my-order-agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Handles order + returns inquiries via Salesforce",
    "allowedReturnUrls": ["https://myapp.com/callback"]
  }' | jq .

Delete an Identity

Warning: Deleting an identity is irreversible.

curl -s -X DELETE "https://agentbase.api.vngcloud.vn/identity/api/v1/agent-identities/my-order-agent" \
  -H "Authorization: Bearer $TOKEN"

SDK

Create an Identity

from greennode_agentbase import IdentityClient, IAMCredentials
from greennode_agentbase.identity import CreateAgentIdentityRequest
import asyncio

client = IdentityClient(iam_credentials=IAMCredentials())

identity = asyncio.run(client.create_agent_identity_async(
    request=CreateAgentIdentityRequest(
        name="my-order-agent",
        description="Handles order inquiries via Salesforce",
        allowed_return_urls=[],
    )
))
print(f"Name: {identity.name}, ID: {identity.id}")

Note: IAMCredentials() with no args auto-loads from GREENNODE_CLIENT_ID / GREENNODE_CLIENT_SECRET environment variables or .greennode.json.

List Identities

result = asyncio.run(client.list_agent_identities_async(page=0, size=20))
for identity in result.content:
    print(f"{identity.name} (id: {identity.id})")
print(f"Total: {result.total_elements}")

Get Identity Details

identity = asyncio.run(client.get_agent_identity_async(name="my-order-agent"))
print(f"Name: {identity.name}, ID: {identity.id}")

Update an Identity

from greennode_agentbase.identity import UpdateAgentIdentityRequest

identity = asyncio.run(client.update_agent_identity_async(
    name="my-order-agent",
    request=UpdateAgentIdentityRequest(
        description="Handles order + returns inquiries via Salesforce",
        allowed_return_urls=["https://myapp.com/callback"],
    )
))

Delete an Identity

asyncio.run(client.delete_agent_identity_async(name="my-order-agent"))

Auth & Secrets

An agent identity must exist before creating auth providers. If you haven't created one yet, see Agent Identity above.

Portal

Static API Key Provider

Open https://aiplatform.console.vngcloud.vn/access-control → "Auth Providers"
Click "Create Provider" → select "Static API Key"
Fill in Name (e.g., openai-key) and API Key value
Click Create

Delegated API Key Provider

Open https://aiplatform.console.vngcloud.vn/access-control → Auth Providers
Click "Create Provider" → select "Delegated API Key"
Enter a Name (e.g., user-openai-key) → Create

OAuth2 Provider

Open https://aiplatform.console.vngcloud.vn/access-control → Auth Providers
Click "Create Provider" → select "OAuth2"
Fill in: Name, Client ID, Client Secret, Authorization URL, Token URL
Click Create — the response includes a Callback URL to register in your OAuth2 app

RESTful API

Static API Key Provider

Create:

curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/api-key-providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-key",
    "apikey": "sk-proj-xxxxxxxxxxxxxxxxxxxx"
  }' | jq .

List:

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/api-key-providers?page=0&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Get:

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/api-key-providers/openai-key" \
  -H "Authorization: Bearer $TOKEN" | jq .

Update (key rotation):

curl -s -X PUT "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/api-key-providers/openai-key" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"apikey": "sk-proj-new-key-value"}' | jq .

Delete:

curl -s -X DELETE "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/api-key-providers/openai-key" \
  -H "Authorization: Bearer $TOKEN"

Warning: Deleting a provider immediately revokes access for all running agents using it.

Delegated API Key Provider

Create:

curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/delegated-api-key-providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "user-openai-key"}' | jq .

List:

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/delegated-api-key-providers?page=0&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Get:

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/delegated-api-key-providers/user-openai-key" \
  -H "Authorization: Bearer $TOKEN" | jq .

Delete:

curl -s -X DELETE "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/delegated-api-key-providers/user-openai-key" \
  -H "Authorization: Bearer $TOKEN"

OAuth2 Provider

Create:

curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/oauth2-providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "google-oauth",
    "clientId": "812345678901-abcdefg.apps.googleusercontent.com",
    "clientSecret": "GOCSPX-xxxxxxxxxxxx",
    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token"
  }' | jq .

Response includes callbackUrl — register this in your OAuth2 app.

List:

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/oauth2-providers?page=0&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Get:

curl -s "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/oauth2-providers/google-oauth" \
  -H "Authorization: Bearer $TOKEN" | jq .

Update:

curl -s -X PUT "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/oauth2-providers/google-oauth" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "new-client-id.apps.googleusercontent.com",
    "clientSecret": "GOCSPX-new-secret",
    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token"
  }' | jq .

Delete:

curl -s -X DELETE "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/oauth2-providers/google-oauth" \
  -H "Authorization: Bearer $TOKEN"

Get OAuth2 Token (M2M):

curl -s -X POST "https://agentbase.api.vngcloud.vn/identity/api/v1/outbound-auth/oauth2-providers/google-oauth/agent-identities/my-order-agent/tokens/m2m" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

SDK

Static API Key Provider

from greennode_agentbase.identity import CreateApikeyProviderRequest

provider = asyncio.run(client.create_api_key_provider_async(
    request=CreateApikeyProviderRequest(
        name="openai-key",
        apikey="sk-proj-xxxxxxxxxxxxxxxxxxxx"
    )
))
print(f"Created: {provider.name} (status: {provider.status})")

Delegated API Key Provider

from greennode_agentbase.identity import CreateDelegatedApiKeyProviderRequest

provider = asyncio.run(client.create_delegated_api_key_provider_async(
    request=CreateDelegatedApiKeyProviderRequest(name="user-openai-key")
))

OAuth2 Provider

Create:

from greennode_agentbase.identity import CreateOauth2ProviderRequest

provider = asyncio.run(client.create_oauth2_provider_async(
    request=CreateOauth2ProviderRequest(
        name="google-oauth",
        client_id="812345678901-abcdefg.apps.googleusercontent.com",
        client_secret="GOCSPX-xxxxxxxxxxxx",
        authorization_url="https://accounts.google.com/o/oauth2/v2/auth",
        token_url="https://oauth2.googleapis.com/token",
    )
))
print(f"Callback URL: {provider.callback_url}")

Get OAuth2 Token (M2M):

from greennode_agentbase.identity import GetM2mTokenRequest

result = asyncio.run(client.get_m2m_token_async(
    provider_name="google-oauth",
    agent_identity_name="my-order-agent",
    request=GetM2mTokenRequest()
))
print(f"Access Token: {result.access_token}")

Retrieve Credentials at Runtime

When your agent is deployed on AgentBase Runtime, the runtime automatically injects GREENNODE_CLIENT_ID, GREENNODE_CLIENT_SECRET, and GREENNODE_AGENT_IDENTITY as environment variables. The SDK uses these automatically.

Inject static API key:

from greennode_agentbase import (
    GreenNodeAgentBaseApp, RequestContext, PingStatus,
    requires_api_key, requires_access_token,
)

app = GreenNodeAgentBaseApp()

@app.ping
def health() -> PingStatus:
    return PingStatus.HEALTHY

@app.entrypoint
@requires_api_key(provider_name="openai-key")
def handler(payload: dict, context: RequestContext, openai_key: str) -> dict:
    from openai import OpenAI
    client = OpenAI(api_key=openai_key)
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": payload.get("input", "")}]
    )
    return {"output": response.choices[0].message.content}

Inject OAuth2 access token:

@app.entrypoint
@requires_access_token(provider_name="google-oauth")
def handler(payload: dict, context: RequestContext, google_token: str) -> dict:
    import httpx
    resp = httpx.get(
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        headers={"Authorization": f"Bearer {google_token}"},
    )
    return {"events": resp.json().get("items", [])}

Response Models

AgentIdentityResponse fields:

Field

Type

Description

id

string

Unique UUID identifier

name

string

Identity name (immutable after creation)

description

string

Optional description

allowed_return_urls

list[string]

OAuth2 callback URLs

created_at

datetime

Creation timestamp

updated_at

datetime

Last update timestamp

Troubleshooting

Error

Cause

Fix

401 Unauthorized

Expired or invalid IAM token

Re-obtain token with valid credentials

403 Forbidden

Service account lacks permissions

Attach AgentBaseFullAccess at https://iam.console.vngcloud.vn

409 Conflict

Identity or provider name already exists

Choose a different name

Name validation error

Name doesn't match ^[a-zA-Z0-9_-]+$

Use only alphanumeric, underscore, and hyphen. 3–50 chars

404 Not Found

Provider name does not exist

Verify with a list operation

Agent can't retrieve credential

Identity name missing

Ensure GREENNODE_AGENT_IDENTITY env var is set in the runtime

PreviousGetting Started NextRuntime

Last updated 1 month ago

hashtagCore Concepts

hashtagWhat Is an Identity?

hashtagIdentity vs. Runtime

hashtagOutbound Authentication

hashtagAgent Identity

hashtagPortal

hashtagCreate an Identity

hashtagList Identities

hashtagGet Identity Details

hashtagUpdate an Identity

hashtagDelete an Identity

hashtagRESTful API

hashtagCreate an Identity

hashtagList Identities

hashtagGet Identity Details

hashtagUpdate an Identity

hashtagDelete an Identity

hashtagSDK

hashtagCreate an Identity

hashtagList Identities

hashtagGet Identity Details

hashtagUpdate an Identity

hashtagDelete an Identity

hashtagAuth & Secrets

hashtagPortal

hashtagStatic API Key Provider

hashtagDelegated API Key Provider

hashtagOAuth2 Provider

hashtagRESTful API

hashtagStatic API Key Provider

hashtagDelegated API Key Provider

hashtagOAuth2 Provider

hashtagSDK

hashtagStatic API Key Provider

hashtagDelegated API Key Provider

hashtagOAuth2 Provider

hashtagRetrieve Credentials at Runtime

hashtagResponse Models

hashtagTroubleshooting

Core Concepts

What Is an Identity?

Identity vs. Runtime

Outbound Authentication

Agent Identity

Portal

Create an Identity

List Identities

Get Identity Details

Update an Identity

Delete an Identity

RESTful API

Create an Identity

List Identities

Get Identity Details

Update an Identity

Delete an Identity

SDK

Create an Identity

List Identities

Get Identity Details

Update an Identity

Delete an Identity

Auth & Secrets

Portal

Static API Key Provider

Delegated API Key Provider

OAuth2 Provider

RESTful API

Static API Key Provider

Delegated API Key Provider

OAuth2 Provider

SDK

Static API Key Provider

Delegated API Key Provider

OAuth2 Provider

Retrieve Credentials at Runtime

Response Models

Troubleshooting