Authentication

Client credentials#

By default a client authenticates with the OAuth2 client-credentials grant, using the client ID and client secret of an application created in the Equinix Developer Platform.

import com.eqixiac.equinix.Equinix;
import com.eqixiac.equinix.Fabric;
import com.eqixiac.equinix.core.auth.BasicEquinixCredentials;

BasicEquinixCredentials credentials = new BasicEquinixCredentials("CLIENT_ID", "CLIENT_SECRET");
Fabric fabric = new Fabric(credentials);

The client requests a token on the first authenticated call and again when the token expires. When several concurrent requests need a token, the client sends one token request for all of them. Calling authenticate() forces the first token request and, by default, also loads the metro catalog.

The SDK no longer offers the resource-owner password grant, because Equinix ended support for it in January 2025 and the token endpoint accepts client credentials only.

Credential providers#

To read credentials from a secrets manager, or to rotate them without rebuilding the client, implement EquinixCredentialsProvider. The SDK calls it on every authentication, which is the first call and each re-authentication.

import com.eqixiac.equinix.core.auth.EquinixCredentialsProvider;

EquinixCredentialsProvider provider =
    () -> new BasicEquinixCredentials(System.getenv("EQUINIX_ACCESS_KEY"), System.getenv("EQUINIX_SECRET_KEY"));
Equinix eq = new Equinix(provider);

Bearer tokens New in 4.0#

Some endpoints reject a client-credentials token. The case confirmed against the live service on 2026-11-11 is IAM: /v1/projects/{project}/roles and principalPolicies answer "only supported when using an access-policy auth token". Those endpoints need an access-policy token issued by STS.

A BearerTokenProvider supplies tokens obtained elsewhere in place of client credentials, and Equinix and every domain client have a constructor that takes one.

import com.eqixiac.equinix.IAM;
import com.eqixiac.equinix.core.auth.BearerToken;
import com.eqixiac.equinix.core.auth.BearerTokenProvider;

// A fixed token. The SDK cannot renew it.
IAM fixed = new IAM(BearerTokenProvider.of(accessPolicyToken));

// A supplier. The SDK calls it for the first request, shortly before a known expiry, and once after a 401.
IAM rotating = new IAM(BearerTokenProvider.from(
    () -> new BearerToken(System.getenv("EQUINIX_ACCESS_POLICY_TOKEN"), Instant.now().plusSeconds(3000))));

BearerToken is a record of the token value and an optional expiry. BearerToken.of(value) creates one with no known expiry, and the SDK then asks for a new token only after a 401.

Access-policy token from STS#

The following block exchanges an OIDC ID token for an Equinix access-policy token, without a client secret, and uses the token for a project-scoped IAM call.

import com.eqixiac.equinix.STS;
import com.eqixiac.equinix.iam.model.json.RoleList;
import com.eqixiac.equinix.sts.model.StsScope;
import com.eqixiac.equinix.sts.model.StsToken;
import com.eqixiac.equinix.sts.model.json.creators.TokenRequest;

STS sts = STS.withoutCredentials();

BearerTokenProvider fromSts = BearerTokenProvider.from(() -> {
    StsToken token = sts.tokens().generate(new TokenRequest()
        .grantType("urn:ietf:params:oauth:grant-type:token-exchange")
        .subjectToken(oidcIdToken)
        .subjectTokenType("urn:ietf:params:oauth:token-type:id_token")
        .scope(StsScope.accessPolicy("access-policy-id", "idp-name")));
    return new BearerToken(token.getAccessToken(), Instant.now().plusSeconds(token.getExpiresIn()));
});

IAM iam = new IAM(fromSts);
RoleList roles = iam.roles().listByProject(projectId);

The live service accepts a scope that is an access-policy ERN or one of the roleassignments:, projectpolicies: and principalpolicy: forms. StsScope builds each of them. The live validation of 2026-11-11 verified the request format and the error shape of the token exchange and did not re-verify the shape of a successful response.

Unauthenticated STS operations#

The token exchange, listAccessPoliciesGranted, JWKS and OpenID discovery are public operations, and the SDK sends them without a bearer header and without an Equinix login. STS.withoutCredentials() creates a client for these operations for a workload that holds an ID token and no Equinix credentials. Managing OIDC providers requires credentials, through new STS(credentials).

Hosts#

Release 3.0.0 sent IAM and STS requests to api.equinix.com, which answers 404 for both. The 4.0 tree uses the hosts their specifications declare. To send one area elsewhere, for example through a proxy, call getEquinixClient().setDomainEndPoint("STS", url) on the domain client. The host is resolved in this order: the domain override, then setEndPoint(...), then the host the SDK's catalogue records for the area, then the default.

Sandbox#

EquinixConfig.builder().sandbox(true) targets the Equinix sandbox environment. The two-argument constructors new Fabric(credentials, true) do the same.