Credential injection

Use credential injection when code in a Sailbox needs to call an HTTPS API with an API key or token. Store the credential as a secret for your organization, then attach an HTTP policy that adds it to matching requests. Your code sends a normal request without the credential, and Sail adds the credential before sending the request to the matched API. Sail’s secret APIs never return a stored value.

Set up credential injection

This example stores a GitHub token, creates a policy for api.github.com, and attaches the policy to an existing Sailbox. The policy adds the token to the authorization header on HTTPS requests to that host. In the CLI example, replace the example Sailbox and policy IDs with your own. sail box list shows your Sailbox IDs, and the create command prints the new policy ID. In the SDK examples, sailbox refers to a Sailbox you created earlier.

# Enter the token at the hidden prompt.
sail secret set GITHUB_TOKEN

cat > github-policy.json <<'JSON'
{
  "api.github.com": {
    "rules": [
      {
        "request": {
          "set": {
            "headers": {
              "authorization": "Bearer ${secrets.GITHUB_TOKEN}"
            }
          }
        }
      }
    ]
  }
}
JSON

sail http-policy create github --file github-policy.json
sail box http-policy set sb_abc123 hp_abc123

import os

import sail

sail.Secret.set("GITHUB_TOKEN", os.environ["GITHUB_TOKEN"])

policy = sail.HttpPolicy.create(
    "github",
    {
        "api.github.com": {
            "rules": [
                {
                    "request": {
                        "set": {
                            "headers": {
                                "authorization": "Bearer ${secrets.GITHUB_TOKEN}",
                            },
                        },
                    },
                },
            ],
        },
    },
)

sailbox.set_http_policy(policy)

import { HttpPolicy, Secret } from "@sailresearch/sdk";

await Secret.set("GITHUB_TOKEN", process.env.GITHUB_TOKEN!);

const policy = await HttpPolicy.create("github", {
  "api.github.com": {
    rules: [
      {
        request: {
          set: {
            headers: {
              authorization: "Bearer ${secrets.GITHUB_TOKEN}",
            },
          },
        },
      },
    ],
  },
});

await sailbox.setHttpPolicy(policy);

use sail::Client;
use serde_json::json;

let client = Client::from_env()?;

client
    .set_secret("GITHUB_TOKEN", &std::env::var("GITHUB_TOKEN")?)
    .await?;

let policy = client
    .create_http_policy(
        "github",
        &json!({
            "api.github.com": {
                "rules": [
                    {
                        "request": {
                            "set": {
                                "headers": {
                                    "authorization": "Bearer ${secrets.GITHUB_TOKEN}",
                                },
                            },
                        },
                    },
                ],
            },
        }),
    )
    .await?;

sailbox.set_http_policy(&policy).await?;

The secret and policy belong to your organization. You can attach the same policy to more than one Sailbox. Each Sailbox can have one policy attached at a time.

Choose which requests receive a credential

The rules in a policy are grouped by hostname. Write only the hostname, such as api.github.com. Do not include https://, a port, or a path. You can use a wildcard like *.example.com or the catch-all * as a host, but prefer a plain hostname where possible. A wildcard such as *.example.com sends the credential to every matching direct subdomain. Use a wildcard only when you trust every matching host. The example has no match field, so its rule covers every request to api.github.com. You can add a match field to limit a rule by request method, path, headers, or query parameters. See HTTP policies for more rule examples and options. Credential injection works only for HTTPS requests. Plain HTTP and raw TCP connections are unchanged, and so is a connection from a rare HTTPS client that does not announce its HTTP version while connecting; the limitations in HTTP policies section shows how you can handle this case.

Use a stored secret

Write ${secrets.NAME} where a stored value should appear. In the example, ${secrets.GITHUB_TOKEN} refers to the organization secret named GITHUB_TOKEN. A policy can insert a secret inside request.set.headers or request.set.query. Secret names start with a letter or number, can contain letters, numbers, underscores, and dashes, and can be up to 128 characters. A value cannot be empty, can be up to 64 KiB, and must be one line of text: no ASCII control characters such as tabs or line breaks. Get and list calls return a secret’s name and timestamps, never its value. If you set the same name again, Sail updates that organization secret. After the update call succeeds, the next matching request from any Sailbox whose attached policy uses it gets the new value.

Replace or clear a policy

Attaching a policy replaces the policy currently attached to that Sailbox, and clearing it leaves the Sailbox with no policy. The change affects HTTPS connections the Sailbox opens after the call succeeds; a connection that is already open keeps the previous policy until it closes. Policy documents cannot change after creation. To change the rules, create a new policy and attach it. HTTP policies covers attachment in detail.

Delete policies and secrets

You cannot delete a policy while it is attached to a Sailbox. You also cannot delete a secret while any policy refers to it. Delete resources in this order:

Clear or replace the policy on every Sailbox that uses it.
Delete every policy that refers to the secret.
Delete the secret.

sail http-policy list shows how many Sailboxes use each policy and which secret names it refers to. For forwarding, policy-generated responses, and other request changes, see HTTP policies.

Getting started

Inference

Guides

Sailbox

Voyages

Security & compliance

Set up credential injection

Choose which requests receive a credential

Use a stored secret

Replace or clear a policy

Delete policies and secrets

​Set up credential injection

​Choose which requests receive a credential

​Use a stored secret

​Replace or clear a policy

​Delete policies and secrets

Set up credential injection

Choose which requests receive a credential

Use a stored secret

Replace or clear a policy

Delete policies and secrets