Get started with the Aembit Edge SDK

In this quickstart, you configure Aembit in the console, install the TypeScript Edge SDK, and run a short program that retrieves a credential. The console side defines which workload may receive which credential, and the code side presents the workload’s identity and asks for it.

This guide walks you through the following primary steps:

Configure your Aembit Tenant
Install the Edge SDK
Retrieve a credential

Before you begin

This quickstart assumes you have a basic understanding of how Aembit works.

To follow this quickstart, you must have the following:

The tenantId from your (https://<tenantId>.aembit.io).
Create a free Aembit Tenant if you don’t have one.
Node.js 20 or later.
An OpenID Connect (OIDC) ID token that identifies the environment your code runs in.

Platforms such as GitHub Actions, GitLab CI, Kubernetes, and Vercel issue OIDC ID tokens. For this quickstart you paste one token into the program, so any OIDC ID token you can copy works. The Edge API quickstart shows one way to generate and decode a token from a GitHub or GitLab CI job.

Step 1: Configure your Aembit Tenant

In this step, you create the five Aembit components that authorize your program’s first credential:

A that verifies the identity your code presents.
A that represents your program.
A that supplies the credential.
A that represents the service the credential is for.
An that ties the other four components together.

Create a Trust Provider

The OIDC ID Token Trust Provider validates any standards-compliant OIDC ID token, which keeps this quickstart independent of where your code runs.

Read the issuer and subject values off a real token rather than guessing them. Decode your token, then copy the iss and sub claims you actually see into the following steps.

Log into your Aembit Tenant at https://<tenantId>.aembit.io and go to Trust Providers in the left sidebar menu.

Click + New.
Fill out the Trust Provider form:
- Name - Enter a descriptive name like Edge SDK Quickstart.
- TRUST PROVIDER - Select OIDC ID Token, which reveals its configuration options.
- Attestation Method - Select OIDC Discovery and enter your identity provider’s main URL, which matches the token’s iss claim.
- Match Rules - Select iss and enter the same issuer URL as the Value.
Click Save.
Click your new Trust Provider and copy the value, because your program passes it to Aembit with every authentication request.

To find this value again later, see Get your Edge SDK Client ID.

Create a Client Workload

The Client Workload represents your program in the Access Policy, and Aembit matches it against the claims in your token.

While still in your Aembit Tenant, go to Client Workloads in the left sidebar menu.

Click + New.
Fill out the Client Workload form:
- Name - Enter a descriptive name like Edge SDK Quickstart App.
- Client Identification - Select OIDC ID Token Subject and enter your token’s sub claim as the Value.
Click Save.

Create a Credential Provider

The Credential Provider defines the credential your program retrieves. This quickstart uses a static API key, because it needs no integration with an external secrets store.

While still in your Aembit Tenant, go to Credential Providers in the left sidebar menu.

Click + New.
Fill out the Credential Provider form:
- Name - Enter a descriptive name like My Service API Key.
- Credential Type - Select API Key.
- API Key - Enter an API key for your target service, like my_secure_api_key_abc123xyz789.
Click Save.

Create a Server Workload

The Server Workload represents the target service your program requests a credential for. For this quickstart it’s a placeholder rather than a real service, because the goal is to demonstrate the retrieval flow.

While still in your Aembit Tenant, go to Server Workloads in the left sidebar menu.

Click + New.
Fill out the Server Workload form’s Service Endpoint section:
- Host - Enter api.myservice.com.
- Application Protocol - Select HTTP, which sets the Port to its default of 80.
Leave the remaining fields at their default values.

Record the host and port, because the values in your program must match them exactly.
Click Save.

Create an Access Policy

The Access Policy ties the four components together: it permits the Client Workload, verified by the Trust Provider, to receive the Credential Provider’s credential for the Server Workload. Without it, Aembit denies the credential request.

While still in your Aembit Tenant, go to Access Policies in the left sidebar menu.

Click + New to open the Access Policy Builder.
In the Name field, enter a descriptive name like Edge SDK Quickstart Policy, then click Save.
In the Client Workload card in the right panel, click + Configure, then select the Select Existing tab.

Select the Client Workload you created earlier and click Use Selected.
In the Server Workload card, click + Configure, then select the Select Existing tab.

Select the Server Workload you created earlier and click Use Selected.
In the Trust Provider card, click + Configure, then select the Select Existing tab.

Select the Trust Provider you created earlier and click Use Selected.
In the Credential Provider card, click + Configure, then select the Select Existing tab.

Select the Credential Provider you created earlier and click Use Selected.
Click Save Policy & Activate.

Your Aembit Tenant is now configured, and the remaining steps happen in code.

Step 2: Install the Edge SDK

In your project directory, install the SDK from npm:

npm install @aembit/edge-sdk

Step 3: Retrieve a credential

Create a file named quickstart.ts with the following program:

import { EdgeClient, trustProviders } from "@aembit/edge-sdk";

const client = new EdgeClient({
  baseUrl: "https://<tenant>.ec.<region>.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: trustProviders.oidcIdToken({
    identityToken: "your-oidc-id-token",
  }),
});

const credential = await client.getCredential({
  server: {
    host: "api.myservice.com",
    port: 80,
  },
  credentialType: "ApiKey",
});

console.log({
  credentialType: credential.credentialType,
  expiresAt: credential.expiresAt,
  dataKeys: Object.keys(credential.data),
});

The program builds an EdgeClient, presents your OIDC ID token through the Trust Provider, and requests the credential your Access Policy grants. It prints the credential type and the keys in the payload rather than the secret itself.

Fill in your values

Set baseUrl to your tenant’s Edge API base URL.

To find it, hover over your username in the bottom left corner of your Aembit Tenant, select Profile, and copy the Edge API Base URL field. The form is https://<tenant>.ec.<stack>.aembit.io. Use this final host, because a URL that redirects fails against the credentials endpoint instead of following the redirect.
Set clientId to the Edge SDK Client ID you copied from your Trust Provider.
Set identityToken to your decoded OIDC ID token, which starts with ey.

A static string suits this quickstart, because you run the program once. In a long-running application, pass a function that returns a fresh token instead, because OIDC ID tokens are short-lived. The examples in the SDK repository show per-platform Trust Providers that collect identity evidence automatically, with no token handling in your code.
Confirm host and port match the Service Endpoint on your Server Workload exactly.

A mismatch returns a response that looks successful but carries no credential.
Confirm credentialType is ApiKey, matching your Credential Provider.

Run the program

Run the file with a TypeScript runner such as tsx:

npx tsx quickstart.ts

A working flow reports the credential type and the keys in the payload:

{
  credentialType: 'ApiKey',
  expiresAt: '2026-08-26T19:19:09.2559713Z',
  dataKeys: [ 'apiKey' ]
}

The apiKey entry in credential.data holds the value you entered in your Credential Provider, and your program can now pass it to the target service.

Troubleshooting

Aembit returns 401 from the credentials endpoint. Confirm baseUrl is the final Edge host and that it returns no redirect. Then confirm your token hasn’t expired, because OIDC ID tokens are short-lived, and generate a fresh one if needed. Finally, confirm the Trust Provider’s match rules line up with the claims in your real token.

You get a response, but the credential type is Unknown and dataKeys is empty. The request reached Aembit and failed to match a policy. Check host and port against the Server Workload first, then credentialType, then the sub claim matching on the Client Workload.

What’s next

Follow a runnable example in the SDK repository to replace the pasted token with a Trust Provider that collects identity evidence from your platform automatically.
Browse the SDK repository for the developer reference.
See the Edge API for the REST interface the SDK wraps.