Set up an Orb service credential

An Orb service credential lets a Glean agent read billing data from Orb through the Orb API. The credential uses an Orb API key, which Glean injects as a bearer token when the agent makes a request. The agent does not need to see or manage the API key.

Prerequisites

• An Orb account with access to the Orb dashboard.
• Permission to create an API key in Orb.
• A Glean deployment with the Orb service credential available.
• A Glean administrator who can create service credentials and attach them to an agent.

Create an API key in Orb

Create a dedicated API key for Glean rather than reusing a key used by another integration.

1. Sign in to the Orb dashboard.
2. Start in Test Mode if you are setting up or validating the integration. Test and live accounts are separate and require separate API credentials.
3. Open Developers → API Keys.
4. Create an API key and give it a descriptive name, such as glean-agent-read-only.
5. Copy the key and store it securely. Do not paste it into an agent prompt, skill, source file, ticket, or chat message.

Use a live-mode key only when the agent is ready to read production billing data. For details, see Orb's first usage event guide and core concepts.

Create the service credential in Glean

1. Go to Admin console → Platform → Tools → Service credentials.
2. Select Add, then Orb.
3. Enter a credential name and description.
4. Paste the Orb API key into API Key.
5. Set the Audience to the users or groups allowed to attach this credential to agents.
6. Select Save.

Glean uses the key to authenticate requests to https://api.withorb.com/v1. Do not add an Authorization header yourself when using the Orb skill.

Attach and verify the credential

1. Open the agent.
2. Select Tools → Service credentials.
3. Attach the Orb credential and save the agent.
4. Ask the agent to perform a read-only test, such as: "List the first five plans in Orb."

You can also test with a customer or subscription lookup if suitable test data exists in the selected Orb account. The orb_api skill explains supported endpoints, query parameters, pagination, and error responses.

Supported access

The Orb credential is read-only. It permits GET requests to api.withorb.com and supports reading:

• Customers, including lookup by Orb ID or external customer ID
• Subscriptions and subscription usage
• Invoices
• Alerts
• Customer credits
• Plans

The credential does not permit creating, updating, ingesting, issuing, voiding, or deleting Orb data. Non-GET requests are denied.

Security guidance

• Use a dedicated key for the Glean agent.
• Never include the API key in prompts, source code, screenshots, logs, or documentation.
• Limit access to the credential through its audience settings.
• To rotate a key, create a replacement in Orb, update the key in the Glean service credential, then revoke the old key in Orb.
• Revoke and replace the key in Orb if it is exposed or no longer needed.

Troubleshooting

Verify that the API key is valid and belongs to the intended Orb test or live account. Create a new key if the original was revoked or copied incorrectly.

Check whether the identifier is an Orb ID or an external customer ID, and verify that it belongs to the selected Orb account.

Confirm that the credential uses the same Orb mode, test or live, as the data you expect to read.

Confirm that the Orb credential is enabled for the deployment and that its audience allows the user or group to attach it.

See also

• Agent identity overview
• Create an independent agent
• Orb API reference
• Orb authentication and API key setup