Identity Providers

Identity providers are where you store credentials. Create a provider, add secrets (key/value pairs) under it, then attach those secrets to a runtime (sandbox). On each run_code / run_cmd, the attached secrets become environment variables — without putting keys in your source or prompts.

Manage Identity providers in Identity → Providers on the platform, or via client.identity.providers / /v1/identity/providers. Create secrets under a provider there. Secret values are write-only — list/get return masked placeholders only.

Why Identity providers?

Without	With
Keys in prompts or scripts	Secrets stored under an Identity provider
Copy keys into every sandbox	Attach secrets once; reuse across runtimes
Painful rotation	Update the secret; next execution uses the new value

Secrets are resolved at execution time. They are not stored in the runtime’s persisted env record.

Behavior

Secret keys become env var names (OPENAI_API_KEY).
Same key under an Identity provider overwrites the previous value.
Attach secrets when creating a sandbox (providers=[...]) or later with client.identity.providers.attach(...).
After detach, the next execution no longer receives those secrets.
Interactive terminal/SSH does not auto-inherit secrets — use run_code or run_cmd.

Create an Identity provider and secrets

from gravixlayer import GravixLayer

client = GravixLayer()

provider = client.identity.providers.create(
    name="OpenAI",
    provider_type="api_key",
    secrets=[{"key": "OPENAI_API_KEY", "value": "sk-..."}],
)
print(provider.id)

curl -X POST "https://api.gravixlayer.ai/v1/identity/providers" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI",
    "provider_type": "api_key",
    "secrets": [
      {"key": "OPENAI_API_KEY", "value": "sk-..."}
    ]
  }'

Multiple secrets

One Identity provider can hold several keys:

provider = client.identity.providers.create(
    name="External APIs",
    provider_type="api_key",
    secrets=[
        {"key": "OPENAI_API_KEY", "value": "sk-..."},
        {"key": "ANTHROPIC_API_KEY", "value": "sk-ant-..."},
        {"key": "GITHUB_TOKEN", "value": "ghp_..."},
    ],
)

curl -X POST "https://api.gravixlayer.ai/v1/identity/providers" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External APIs",
    "provider_type": "api_key",
    "secrets": [
      {"key": "OPENAI_API_KEY", "value": "sk-..."},
      {"key": "ANTHROPIC_API_KEY", "value": "sk-ant-..."},
      {"key": "GITHUB_TOKEN", "value": "ghp_..."}
    ]
  }'

Attach secrets when creating a sandbox

Pass the Identity provider ID so its secrets are attached to the sandbox:

runtime = client.runtime.create(
    template="base-small",
    providers=[provider.id],
)

result = runtime.run_code(
    code="import os; print('ok' if os.environ.get('OPENAI_API_KEY') else 'missing')"
)
print(result.text)

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base-small",
    "cloud": "azure",
    "region": "eastus2",
    "providers": ["PROVIDER_ID"]
  }'

Attach secrets to a running sandbox

client.identity.providers.attach(provider.id, runtime.runtime_id)

result = runtime.run_code(
    code="import os; print(os.environ['OPENAI_API_KEY'][:7])"
)

curl -X POST "https://api.gravixlayer.ai/v1/identity/providers/PROVIDER_ID/attach" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runtime_id": "RUNTIME_ID"}'

Use credentials in code

result = runtime.run_code(code="""
import os
import urllib.request

req = urllib.request.Request(
    "https://api.openai.com/v1/models",
    headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
)
print(urllib.request.urlopen(req).status)
""")
print(result.text)

Detach secrets

client.identity.providers.detach(provider.id, runtime.runtime_id)

result = runtime.run_code(
    code="import os; print(os.environ.get('OPENAI_API_KEY', 'missing'))"
)

runtime.kill()
client.identity.providers.delete(provider.id)

curl -X DELETE \
  "https://api.gravixlayer.ai/v1/identity/providers/PROVIDER_ID/attach/RUNTIME_ID" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

SDK reference

All Identity provider operations live under client.identity.providers (maps to /v1/identity/providers).

Method	Purpose
`create(...)`	Create an Identity provider (optional initial secrets)
`list(...)`	List Identity providers (masked)
`get(provider_id)`	Get one Identity provider (masked secrets)
`update(provider_id, ...)`	Update name, type, or `is_active`
`delete(provider_id)`	Soft-delete the Identity provider
`add_secret(provider_id, key, value)`	Add or upsert a secret pair
`list_secrets(provider_id)`	List secret keys (values masked)
`update_secret(provider_id, secret_id, ...)`	Rename key and/or replace value
`delete_secret(provider_id, secret_id)`	Delete a secret pair
`attach(provider_id, runtime_id)`	Attach the provider’s secrets to a runtime
`detach(provider_id, runtime_id)`	Detach those secrets from a runtime
`list_for_runtime(runtime_id)`	List providers whose secrets are attached to a runtime

# Provider CRUD
providers = client.identity.providers.list()
provider = client.identity.providers.get(provider.id)
client.identity.providers.update(provider.id, name="OpenAI Prod", is_active=True)
client.identity.providers.delete(provider.id)

# Secret pair CRUD
client.identity.providers.add_secret(provider.id, key="OPENAI_API_KEY", value="sk-...")
secrets = client.identity.providers.list_secrets(provider.id)
client.identity.providers.update_secret(provider.id, secret_id, value="sk-new-...")
client.identity.providers.delete_secret(provider.id, secret_id)

# Attach / detach
client.identity.providers.attach(provider.id, runtime.runtime_id)
client.identity.providers.list_for_runtime(runtime.runtime_id)
client.identity.providers.detach(provider.id, runtime.runtime_id)

CLI

gravixlayer provider create --name OpenAI --type api_key \
  --secret OPENAI_API_KEY=sk-...

gravixlayer runtime create --template base-small \
  --provider PROVIDER_ID

gravixlayer provider list-attached RUNTIME_ID
gravixlayer provider detach PROVIDER_ID RUNTIME_ID

Security best practices

Identity providers keep secrets out of your source tree and make rotation easier — but attaching secrets still injects those values into the sandbox as environment variables on run_code / run_cmd. Isolation from the host does not stop a context-injected agent from reading os.environ, writing files, or sending data over the network.

Prefer keeping high-value credentials in tools that run outside the sandbox. Let the agent call those tools; do not put the raw key where guest code can print or exfiltrate it. Attach secrets when the workload truly must authenticate from inside the runtime — and design for least privilege.

Safer patterns

Authenticate outside the sandbox — your app or a host-side tool holds the API key; the sandbox only receives non-sensitive results.
Narrow Identity secrets — one provider per integration, keys scoped to the minimum API surface, rotate often, detach when unused.
Limit what can leave the box — use Network Policies to allowlist or block outbound destinations; monitor for unexpected destinations.
Human review for risky actions — require approval before tool calls that spend money, change production data, or leave the sandbox.
Treat sandbox I/O as hostile — validate outputs, redact secrets from logs, and never trust agent-generated commands blindly.

Short-lived or scoped credentials inside a sandbox are still readable by any code that runs there. If an attacker can steer the agent, they can usually read those values too. Injection into the runtime is a convenience tradeoff, not a security boundary.

For broader sandbox hardening, see Runtime overview — Security best practices.

Create Runtime

Create a sandbox and attach secrets

Network Policies

Limit where secrets can be used over the network

Getting Started

Runtime

Integrations

Support

Why Identity providers?

Behavior

Create an Identity provider and secrets

Multiple secrets

Attach secrets when creating a sandbox

Attach secrets to a running sandbox

Use credentials in code

Detach secrets

SDK reference

CLI

Security best practices

Safer patterns

Next

Create Runtime

Network Policies

​Why Identity providers?

​Behavior

​Create an Identity provider and secrets

​Multiple secrets

​Attach secrets when creating a sandbox

​Attach secrets to a running sandbox

​Use credentials in code

​Detach secrets

​SDK reference

​CLI

​Security best practices

​Safer patterns

​Next

Create Runtime

Network Policies

Why Identity providers?

Behavior

Create an Identity provider and secrets

Multiple secrets

Attach secrets when creating a sandbox

Attach secrets to a running sandbox

Use credentials in code

Detach secrets

SDK reference

CLI

Security best practices

Safer patterns

Next