Skip to content

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.

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:

Sequence showing the Edge SDK collecting identity evidence, authenticating to Aembit Cloud when its cached access token cannot serve the request, then requesting the credential that Aembit Cloud returns after Access Policy evaluation

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.

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.

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.

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.

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.

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 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.

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 SDKAembit componentWhat Aembit does with it
The client IDTrust ProviderPicks the Trust Provider that verifies the authentication request
The Trust Provider objectTrust ProviderSupplies evidence, which must suit the configured Trust Provider type
The identity evidence in each credential requestClient WorkloadMatches the Client Workload’s Client Identification values
The host and port of the target serviceServer WorkloadMatches the Host and Port under Service Endpoint
Nothing directlyAccess PolicyConnects the Client Workload to the Server Workload
Connection metadata, when you set itCredential ProviderPicks one of the Access Policy’s Credential Providers
The credential typeCredential ProviderPicks which fields of the credential Aembit fills
The Resource Set ID, when you set oneResource SetScopes 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.