Integration with API Key

While the SiX IDaaS & IAM Console provides a comprehensive UI for managing authentication and authorization assets, certain business models require automated or programmatic management. For these scenarios, SiX IDaaS & IAM provides Integration Keys (API Keys) to interact with our RESTful APIs.

Use Cases for Integration Keys

1. Programmatic Asset Management

If your workflow involves managing tenancy assets—such as users, groups, or application configurations—via code rather than a manual interface, Integration Keys serve as the secure credentials for these administrative API calls.

2. Securing Your Own APIs

If you are developing your own APIs based on our IAM framework and plan to expose them to your customers, Integration Keys can be used to enforce fine-grained access control. This allows you to authenticate external systems or third-party developers who consume your services.

Authorization Model

Integration Keys follow an authorization model similar to that of a standard Identity Application (IdP) User, providing a consistent management experience:

• Group-Based Permissions: You can assign an Integration Key to specific Groups to inherit predefined permission sets.
• Custom Properties: You can attach metadata or Customized Properties to a key, allowing your backend logic to handle specialized routing or multi-tenancy contexts.

Interaction flows

See the Develop your own APIs based on IAM page and the Architecture section.

Basic Steps to access platform APIs

Use below steps to create Integration Key to access the platform or your own developed APIs.

WARNING

Integration Key need first authenticate itself util it can successfully access the platform APIs.

1. Create the Integration Key and grant authorization

Login SiX IDaaS & IAM console, navigate to "Service/Integration Key -> Create Integration Key" to create one Integration Key as instruction.

TIP

Integration Key need first authenticate itself util it can successfully access the platform APIs.

Download the RSA256 private key and copy the key id to your local PC for later usage.

WARNING

The RSA256 private key will only appear once on the console and it will NOT be persisted in the SiX IDaaS & IAM tenancy store.

Never expose this key for unintentional use as it act as the credentials for the Integration Key!

Grant the authorization by setting the properties of the key and/or putting it into different authorization groups as your design.

2. Authenticate the Integration Key and get access token

Generate the JWT using the RSA256 private key and key id

Use the private key you downloaded and the key id to create a JWT and sign it.

The sample code snippet to create JWT:

Create JWT and sign it with private key

  public static String createJwtBearerTokenWithRsaPrivateKey(String pemEncodedRSAPrivateKey, String keyId, int expiringInSeconds) throws JOSEException {
        //Convert the x509 RSA private key in PEM format to JWK
        JWK jwk = JWK.parseFromPEMEncodedObjects(pemEncodedRSAPrivateKey);
        RSAKey rsaJWK = jwk.toRSAKey();
        long expiringTime = new Date().getTime() + expiringInSeconds * 1000;
        JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
                .subject(keyId) //set the keyId as subject
                .expirationTime(new Date(expiringTime))
                .build();
        SignedJWT signedJWT = new SignedJWT(
                new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(keyId).build(),
                claimsSet);
        //Create signer from the private key
        JWSSigner signer = new RSASSASigner(rsaJWK);
        signedJWT.sign(signer);
        String jwt = signedJWT.serialize();
        System.out.println(jwt);
        return jwt;
    }

Use the JWT to exchange the access token

Use the "/oauth2/token" endpoint to exchange the JWT for access token, the authorization headers need to be as:

Header Name	Header value
assertion	$JWT
grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer

3. Use the access token to access the platform APIs.

Put the access token in the "Authorization: Bearer ${access token}" request header, then to access the platform APIs listed in below:

IDaaS & IAM Mgt APIs

Device APIs

Basic Steps to access your own APIs

1. Create the Integration Key and grant authorization

Login SiX IDaaS & IAM console, navigate to "Service/Integration Key -> Create Integration Key" to create one Integration Key as instruction.

TIP

Integration Key need first authenticate itself util it can successfully access the platform APIs.

Download the RSA256 private key and copy the key id to your local PC for later usage.

WARNING

The RSA256 private key will only appear once on the console and it will NOT be persisted in the SiX IDaaS & IAM tenancy store.

Never expose this key for unintentional usage as it act as the credentials for the Integration Key!

Grant the authorization by setting the properties of the key and/or putting it into different authorization groups as your design.

2. Authenticate the Integration Key and get access token

Generate the JWT using the RSA256 private key and key id

Use the private key you downloaded and the key id to create a JWT and sign it.

The sample code snippet to create JWT:

Create JWT and sign it with private key

public static String createJwtBearerTokenWithRsaPrivateKey(String pemEncodedRSAPrivateKey, String keyId, int expiringInSeconds) throws JOSEException {
        //Convert the x509 RSA private key in PEM format to JWK
        JWK jwk = JWK.parseFromPEMEncodedObjects(pemEncodedRSAPrivateKey);
        RSAKey rsaJWK = jwk.toRSAKey();
        long expiringTime = new Date().getTime() + expiringInSeconds * 1000;
        JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
                .subject(keyId) //set the keyId as subject
                .expirationTime(new Date(expiringTime))
                .build();
        SignedJWT signedJWT = new SignedJWT(
                new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(keyId).build(),
                claimsSet);
        //Create signer from the private key
        JWSSigner signer = new RSASSASigner(rsaJWK);
        signedJWT.sign(signer);
        String jwt = signedJWT.serialize();
        System.out.println(jwt);
        return jwt;
    }

Use the JWT to exchange the access token

Use the "/oauth2/token" endpoint to exchange the JWT for access token, the authorization headers need to be as:

Header Name	Header value
assertion	$JWT
grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer

3. Use the access token to access the your own APIs.

Put the access token in your APIs request e.g. in the headers then invoke your own developing APIs.

TIP

Before allowing the APIs access, your resource server need to validate the authenticity of access token first, for more info, please see:

Validate the access token via the JWK

For the access to the platform APIs, this validation will be done out of box.