How the Edge SDK works
The Edge SDK gets a credential for your application in two requests to the Aembit Edge API. The authentication request proves the workload’s identity and returns an access token. The credential request presents that token and returns the credential an Access Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more grants. The TypeScript and Python SDKs behave the same way except where this page says otherwise. The page names each method in both languages, and the developer reference for TypeScript and Python covers installation, Trust Provider: Trust Providers verify identity claims from a workload's runtime environment or an Identity Provider instead of relying on pre-shared secrets. They support workload attestation and user identity validation for blended identity.Learn more setup, and examples.
The request flow
Section titled “The request flow”Your application calls one method, getCredential() in TypeScript or get_credential() in Python.
The SDK authenticates first only when its cached access token cannot serve the request, as
When the SDK authenticates again describes:
Identity evidence
Section titled “Identity evidence”The SDK collects identity evidence at the start of every credential request, even when it holds a valid access token. The Trust Provider object you pass to the client decides where the evidence comes from. A metadata service Trust Provider, such as AWS Metadata Service or Azure Instance Metadata Service, reads a signed identity document from the platform. The AWS Role Trust Provider signs a request with the AWS credentials available to the workload. A token Trust Provider, such as OIDC ID Token or GitHub, uses the identity token your application passes. You pass it as a fixed string or as a function that the SDK calls each time. The Python Kubernetes Service Account Trust Provider reads the service account token file when you pass no token.
Authentication
Section titled “Authentication”The authentication request carries two things: the client ID and the identity evidence. Aembit reads the Trust Provider from the client ID and confirms it is active. It then verifies the evidence against that Trust Provider. When the evidence passes, Aembit returns an access token, and the SDK caches it.
You do not need to call authenticate() yourself, because the credential method authenticates when it needs to.
Call it when you want an authentication failure to surface early, such as at application startup.
It returns the token’s expiry time and the ID of the SDK’s Trust Provider object, and never the access token itself.
Each call to authenticate() sends a new authentication request, even when the cached token is still valid.
The exception is a matching authentication request already in flight, which the call waits for and shares.
Credential retrieval
Section titled “Credential retrieval”The credential request carries the access token and the identity evidence. It also names the host and port of the service your application needs to reach, and the credential type you ask for. Aembit uses the evidence to identify the Client Workload: Client Workloads represent AI agents, software applications, scripts, or automated processes that initiate access requests to Server Workloads. They can act on behalf of a user under blended identity or operate autonomously, as when one service calls another.Learn more, and the host and port to identify the Server Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more. It then finds the Access Policy that connects the two, checks the Access Policy’s Trust Providers and Access Condition: Access Conditions add dynamic, context-aware constraints to authorization by evaluating circumstances like time, location, or security posture to determine whether to grant access.Learn more, and asks its Credential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more for the credential.
The SDK does not cache credentials. Every call to the credential method sends a credential request, even when the access token comes from the cache. When the credential carries an expiry time, your application can reuse it until that time if the service it is for allows that.
How the SDK manages the access token
Section titled “How the SDK manages the access token”The SDK holds the access token in memory, inside the client object. Two client objects never share a token, and nothing survives a process restart, so a new process authenticates again. Create one client and reuse it for the life of your application.
When the SDK authenticates again
Section titled “When the SDK authenticates again”The SDK checks the cached token each time your application requests a credential. It sends a new authentication request when any of these holds:
- The client holds no access token yet.
- The cached token expires within the expiry window, which is 60 seconds by default.
- The request names a different Resource Set: Resource Sets are organizational containers that group Access Policy components together, enabling you to manage configurations across different environments, regions, or use cases.Learn more than the one Aembit issued the cached token for.
- In TypeScript, a token Trust Provider returns a different identity token than the one the cached token came from.
The SDK refreshes only at that check. Nothing renews the token in the background, so a client that sits idle past the token’s expiry authenticates on its next credential request.
The expiry window makes the SDK treat a token as expired before Aembit does, so a request does not carry a token that is
about to expire.
Set it in milliseconds with authExpirySkewMs in TypeScript or auth_expiry_skew_ms in Python.
A client caches one token at a time. An application that alternates between two Resource Sets on one client authenticates on every switch, so use one client for each Resource Set.
In Python, a token Trust Provider whose function returns a new identity token keeps using the cached access token until the expiry window. Aembit still reads the new identity token from each credential request.
Concurrent requests
Section titled “Concurrent requests”When two or more credential requests need a new token at the same moment, the SDK sends one authentication request
and gives its result to each of them.
TypeScript does this for concurrent promises, and Python does it for concurrent threads on one client.
Requests share an authentication request only when they name the same Resource Set and use the same retry settings.
In TypeScript, they must also carry the same identity token from a token Trust Provider.
A call to authenticate() also joins a matching authentication request already in flight.
The SDK also collects identity evidence once and shares it among concurrent requests, for Trust Providers that allow it. Requests that do not overlap still collect fresh evidence each time. That sharing covers the metadata service and AWS Role Trust Providers, and token Trust Providers given a fixed string. A token Trust Provider given a function, or the Python Kubernetes Service Account Trust Provider reading its token file, collects evidence for each request.
When authentication fails
Section titled “When authentication fails”When an authentication request fails, the SDK raises the error to your application.
It also discards the cached token when that token is within its expiry window or past it, and Aembit issued it for
the failed request’s Resource Set.
A cached token outside its expiry window stays in place.
The SDK does not authenticate again when a credential request fails, so a 401 from the credential request reaches
your application as an error.
How the SDK maps to Aembit components
Section titled “How the SDK maps to Aembit components”Each value you give the SDK lines up with a component you configure in your Aembit Tenant: Aembit Tenants serve as isolated, dedicated environments within Aembit that provide complete separation of administrative domains and security configurations.Learn more:
| What you give the SDK | Aembit component | What Aembit does with it |
|---|---|---|
| The client ID | Trust Provider | Picks the Trust Provider that verifies the authentication request |
| The Trust Provider object | Trust Provider | Supplies evidence, which must suit the configured Trust Provider type |
| The identity evidence in each credential request | Client Workload | Matches the Client Workload’s Client Identification values |
| The host and port of the target service | Server Workload | Matches the Host and Port under Service Endpoint |
| Nothing directly | Access Policy | Connects the Client Workload to the Server Workload |
| Connection metadata, when you set it | Credential Provider | Picks one of the Access Policy’s Credential Providers |
| The credential type | Credential Provider | Picks which fields of the credential Aembit fills |
| The Resource Set ID, when you set one | Resource Set | Scopes the Trust Provider lookup and the Access Policy search |
When the credential comes back empty or the request fails, the Edge SDK quickstart troubleshooting section works through each of these components in turn.
The client ID is not a Client Workload identifier
Section titled “The client ID is not a Client Workload identifier”The clientId setting, client_id in Python, takes
the Edge SDK Client ID: A structured identifier that Aembit generates when you configure a Trust Provider, encoding your region, tenant, and Trust Provider. It identifies a Trust Provider rather than an individual Client Workload.Learn more from a Trust Provider’s page in your Aembit
Tenant.
It identifies that Trust Provider, not your workload.
It looks like aembit:useast2:a12bc3:identity:github_idtoken:63ab7be6-9785-4a14-be1c-2acf0253070b, and it ends with
the Trust Provider’s ID.
None of the values under a Client Workload’s Client Identification belong in clientId.
That includes the Aembit Client ID: A UUID that Aembit generates when you choose Aembit Client ID as a Client Workload's Client Identification method. It identifies that single Client Workload.Learn more, a UUID that Aembit generates for one
Client Workload.
Aembit matches the Client Workload from the identity evidence in the credential request, and never from the client ID.
Aembit rejects a clientId that is not in the Edge SDK Client ID format, such as an Aembit Client ID UUID, with a
400 status.
It does so before it looks up a Trust Provider or checks any identity evidence.
An Edge SDK Client ID from another Aembit Tenant gets the same 400.
Because the client ID names a Trust Provider, every workload that attests through that Trust Provider uses the same client ID. When those workloads need different credentials, tell them apart with Client Identification values that their evidence matches. The identifier reference compares the Edge SDK Client ID, the Aembit Client ID, and the Client Workload resource ID.
Related resources
Section titled “Related resources”- Get started with the Aembit Edge SDK configures each component and retrieves a first credential.
- Edge SDK logging and network activity lists the log events that trace token caching and authentication.
- Aembit Edge API documents the two requests the SDK sends.