Edge API - /edge/v1/auth

The authentication endpoint is the entry point for Client WorkloadsClient Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more to establish trust with Aembit EdgeAembit Edge: Aembit Edge represents components deployed within your operational environments that enforce Access Policies by intercepting traffic, verifying identities, and injecting credentials just-in-time.Learn more. It validates Client Workload identity, with many attestation methods available, and returns an access token for subsequent API calls.

How the auth endpoint works

The Aembit Edge API auth endpoint provides a secure way for Client Workloads to authenticate and obtain an access token. The authentication flow consists of the following steps:

1. Identity attestation - Client workloads provide attestation data specific to their environment (AWS, Azure, GCP, Kubernetes, etc.)
2. Trust validation - Aembit Edge validates the attestation against configured Trust ProvidersTrust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more
3. Access Policy evaluation - Aembit evaluates Access PoliciesAccess 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 to match the correct Client Workload and determine which credentials it can access for which Server Workloads
4. (Optional) Resource Set validation - If you specify a Resource SetResource 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, Aembit makes sure the Client Workload only accesses resources within the same Resource Set through the X-Aembit-ResourceSet header
5. Token issuance - Upon successful validation, Aembit Edge API returns an OAuth 2.0-style bearer token

The authentication flow supports multiple attestation methods simultaneously, allowing workloads running in hybrid or multi-cloud environments to provide multiple forms of identity proof.

No bearerToken in Authorization header

This authentication endpoint doesn’t pass a bearerToken in the Authorization header like most other API endpoints.

This means you must call the /auth endpoint first to get a valid access token before calling the /credentials endpoint. If you get any unexpected 401 errors, double-check that you aren’t setting the Authorization header with a Bearer token.

Base structure

The following is the base structure of the authentication endpoint, including headers, request, and response formats:

/edge/v1/auth (POST) {}
├─Headers {}
│  └─X-Aembit-ResourceSet (string, uuid) [optional]
├─Request: AuthRequest {}
│  ├─clientId (string) [Edge Client SDK ID from Trust Provider]
│  └─client: ClientWorkloadDetails {} [Workload attestation data]
└─Response: TokenDTO {}
   ├─accessToken (string, nullable) [Bearer token for API calls]
   ├─tokenType (string, nullable) [Typically "Bearer"]
   └─expiresIn (number) [Token lifetime in seconds]

Client Workload attestation types

The client field supports multiple attestation methods that you can use individually or in combination. Each attestation type provides different identity proof mechanisms based on where your Client Workload is running:

AWS attestation

For workloads running on Amazon Web Services, including EC2 instances, Lambda functions, and ECS containers:

aws: AwsDTO {} [AWS workload attestation]
├─instanceIdentityDocument (string, nullable) [Base64-encoded EC2 instance identity document]
├─instanceIdentityDocumentSignature (string, nullable) [Base64-encoded signature for EC2 verification]
├─lambda: LambdaDTO {} [AWS Lambda specific attestation]
│  └─arn (string, nullable) [Lambda function ARN for identity verification]
├─ecs: AwsEcsDTO {} [AWS ECS container attestation]
│  ├─containerMetadata (string, nullable) [Base64-encoded JSON string containing ECS container metadata]
│  └─taskMetadata (string, nullable) [Base64-encoded JSON string containing ECS task metadata]
└─stsGetCallerIdentity: StsGetCallerIdentityDTO {} [AWS STS identity verification]
   ├─headers {} [HTTP headers for STS GetCallerIdentity request]
   │  └─[key] (string, nullable) [Header name/value pairs]
   └─region (string, nullable) [AWS region for STS GetCallerIdentity request]

Example of an AWS attestation request to an EC2 instance:

{
    "clientId": "<edge-sdk-client-id>",
    "client": {
        "aws": {
            "instanceIdentityDocument":
                "<base64-instance-identity-document>",
            "instanceIdentityDocumentSignature":
                "<base64-signature>",
        }
    }
}

200 OK response:

{
    "accessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkpyR3JLQ0x6RVFN...",
    "tokenType": "Bearer",
    "expiresIn": 3600
}

Google Cloud Platform attestation

For workloads running on Google Cloud Platform (GCP), using GCP identity tokens and instance documents:

gcp: GcpAttestationDTO {} [Google Cloud workload attestation]
├─identityToken (string, nullable) [GCP identity token for workload attestation]
└─instanceDocument (string, nullable) [Base64-encoded GCP instance identity document]

The GCP Identity Token Trust Provider matches on the token’s email claim, so identityToken alone is enough. See Edge API authentication with GCP Identity Token for how to get the token.

Kubernetes attestation

For workloads running in Kubernetes clusters, using service account tokens:

k8s: K8sDTO {} [Kubernetes workload attestation]
└─serviceAccountToken (string, nullable) [Kubernetes service account JWT token]

CI/CD platform attestation

For workloads running in continuous integration and deployment platforms using OpenID Connect (OIDC) identity tokens:

GitHub Actions attestation

github: IdentityTokenAttestationDTO {} [GitHub Actions workflow attestation]
└─identityToken (string, nullable) [GitHub OIDC identity token for workflow verification]

Terraform Cloud attestation

terraform: IdentityTokenAttestationDTO {} [Terraform Cloud workspace attestation]
└─identityToken (string, nullable) [Terraform Cloud OIDC identity token]

GitLab Jobs attestation

gitlab: IdentityTokenAttestationDTO {} [GitLab CI/CD pipeline attestation]
└─identityToken (string, nullable) [GitLab OIDC identity token for pipeline verification]

OIDC ID Token attestation

For workloads that get an ID token from any OpenID Connect provider, including platforms with no dedicated attestation method of their own:

oidc: IdentityTokenAttestationDTO {} [OIDC ID Token attestation]
└─identityToken (string, nullable) [ID token from an OIDC-compliant identity provider]

Aembit validates the signature against keys you supply through the Trust Provider, so this method needs setup that the cloud provider methods don’t. See Edge API authentication with OIDC ID Token.

Additional context

sourceIP (string, nullable) [IP address of the requesting Client Workload]

Note

You don’t have to include the sourceIP in auth requests.