API Reference | Scalekit Docs

Introduction

Scalekit API is modeled around the REST architecture style. That means, our API has predictable resource-oriented URLs, accepts form-encoded request bodies and produces JSON formatted responses, uses standard HTTP verbs and error codes.

Apart from REST APIs, we have published SDKs in some of the popular languages as shown below. You can use these SDKs and integrate with Scalekit much faster.

Some additional instructions around using our APIs

API Endpoint Host must use the Environment URL of the environment you are targeting.
API requests without appropriate authentication headers will fail with 401 status code.

Read below to understand more about how to authenticate the API calls and how to handle errors appropriately.

Just getting Started?

Refer to our Quick Start Guide

Setup SDK

Node.js
Python
Go
Java

npm install @scalekit-sdk/node

pip install scalekit-sdk-python

go get -u github.com/scalekit-inc/scalekit-sdk-go

/* Gradle users - add the following to your dependencies in build file */
implementation "com.scalekit:scalekit-sdk-java:1.0.1"

<!-- Maven users - add the following to your `pom.xml` -->
<dependency>
    <groupId>com.scalekit</groupId>
    <artifactId>scalekit-sdk-java</artifactId>
    <version>1.0.1</version>
</dependency>

API Server Endpoint

# use the environment url found in API Config section
https://yourcompany.scalekit.com

# or, if you have enabled CNAME, you can use that too
https://auth.yoursaas.com

Authentication

Scalekit API uses OAuth2 Client Credentials based authentication. You can view and manage the necessary information from your API Config section in the Scalekit Dashboard.

You will need the following information to authenticate with Scalekit APIs

Client ID
Client Secret
Environment URL

You can obtain a secure token by making POST call to the https://{ENV_URL}/oauth/token endpoint and sending client_id and client_secret as part of the request body.

API Authentication

cURL
Node.js
Python
Go
Java

$ curl https://{ENV_URL}/oauth/token \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id={client_id}' \
  -d 'client_secret={client_secret}' \
  -d 'grant_type=client_credentials'\

import { Scalekit } from '@scalekit-sdk/node';

const scalekit = new Scalekit(
  '<SCALEKIT_ENVIRONMENT_URL>',
  '<SCALEKIT_CLIENT_ID>',
  '<SCALEKIT_CLIENT_SECRET>',
);

from scalekit import ScalekitClient

scalekit_client = ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
)

import (
  "github.com/scalekit-inc/scalekit-sdk-go"
)

func main() {
  scalekitClient := scalekit.NewClient(
    "<SCALEKIT_ENVIRONMENT_URL>",
    "<SCALEKIT_CLIENT_ID>",
    "<SCALEKIT_CLIENT_SECRET>"
  )
}

package com.scalekit;

import com.scalekit.ScalekitClient;

public class Main {
  public static void main(String[] args) {

  ScalekitClient scalekitClient = new ScalekitClient(
      "<SCALEKIT_ENVIRONMENT_URL>",
      "<SCALEKIT_CLIENT_ID>",
      "<SCALEKIT_CLIENT_SECRET>"
    );
  }

Response

{
  "access_token": "DCR5c8139165228a82e442445fe01c16",
  "token_type": "bearer",
  "expires_in": 1799
}

Using Access Token

The access_token is the OAuth access token you need to use for all subsequent API calls to Scalekit.

To make a request to one of our APIs, you need to include the access token in the Authorization header of the request as Bearer 'access_token'.

Please make sure that you keep your Client Secrets safely. Do not share your client secret in publicly accessible areas such as GitHub, client-side code, etc.

Our SDKs will automatically handle the API authentication and error handling to make the job of using our APIs much easier for you.

Using Bearer Token

$ curl --request GET "https://{ENV_URL}/api/v1/organizations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {access_token}"

Error Handling

As mentioned earlier, Scalekit APIs return appropriate HTTP Status Codes along with the detailed error messages in case of invalid usage of APIs.

You can see the list of different HTTP Status Codes and the error message format in the right pane. We strongly recommend you to handle errors gracefully while writing code using our SDKs.

Error Codes

HTTP Status	Description
200 or 201	API request is successful
400	The request was unacceptable, often due to missing a required parameter.
401	Invalid Authentication Headers found in the request.
404	Resource not found
429	Too many requests hit the API too quickly. Retry the request after a cool-off period.
500 or 501 or 504	Something went wrong at our end. These are usually a very rare occurrence. We automatically log these requests for alert our on-call engineers

401: Error Message

{
  "code": 16,
  "message": "Token empty",
  "details": [
    {
      "@type": "type.googleapis.com/scalekit.v1.errdetails.ErrorInfo",
      "error_code": "UNAUTHENTICATED"
    }
  ]
}

Single Sign-on

When you need one of your customers to login via Enterprise SSO, you can redirect them to Scalekit's Authorization URL with necessary details about the organization or the SSO connection. Scalekit will seamlessly deal with integrating with any Identity Provider and exchanges user information via SAML or OIDC or OAuth2.

More details about the Single Sign-on flow is described here

Endpoints

get/oauth/authorize post/oauth/token

Authorization URL

Authorization URL initiates the Login flow with Scalekit.

Scalekit expects atleast one of the following parameters to be present. The parameters are used to determine the SSO connection used to Login in the user.

domain - Email domain of the user. Domain should be mapped to an Organization. The SSO connection from the org would be used to login to the app.

connection_id - ID of the SSO connection. If the Connection's status is active, the user will be redirected to the SSO Connection's identity provider configured.

organization_id - ID of Organization. The user will be redirected to the SSO connection's identity provider configured for that organization.

provider - ID of SSO Provider, Incase of Social Logins . e.g google

Parameters
client_idstringrequired
The client ID string that you obtain from the API Credentials page
redirect_uristringrequired
Determines where the response is sent. The value of this parameter must exactly match one of the authorized redirect values that you set in the API Credentials page (including the HTTP or HTTPS scheme, case, and trailing '/', if any).
domainstring
Domain part of the email address that is mapped to an organization. Example. yourcustomer.com
connection_idstring
Connection ID for which the SSO flow must be initiated for. If the Connection's status is active, the user will be redirected to the SSO Connection's identity provider configured
organization_idstring
Organization ID for which the SSO flow must be initiated for. Based on the organization ID supplied, the user will be redirected to the SSO connection's identity provider configured for that organization.
providerstring
Key for the Social SSO Provider. This is common to all Organizations. e.g. google, github, linkedin, gitlab, microsoft, salesforce
response_typestringrequired
Value must be code
scopestringrequired
Value must be openid email profile
statestring
An opaque string that is round-tripped in the protocol; that is to say, it is returned back as-is as a URI parameter in the Basic flow. The state can be useful for correlating requests and responses. Because your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request initiated by your app.

State will be useful if you would like to retain some information about the user that you would like to use at the end of the login flow. E.g. deep link URL in your product to redirect the user to after a successful login.

If you generate a random string or encode the hash of some client state (e.g., a cookie) in this state variable, you can validate the response to additionally ensure that the request and response originated in the same browser. This additional validation offers protection against attacks such as cross-site request forgery.
noncestring
A random value generated by your app that enables replay protection.
login_hintstring
When your app knows the email address of the user it is trying to authenticate, it can provide this parameter as a hint to the authentication server and Scalekit will pass this information to your customer's identity provider. Some identity providers prefill the login box with this value to make the login experience easier for the end user.
code_challengestring
A challenge code generated from code_verifier that is required for PKCE flows. This is used ensure if the request was handled by the right parties. The string is stored by Scalekit to be used when validating the token request with a code_verifier. A code_challenge is generated as follows code_challenge = SHA256(code_verifier) .
code_challenge_methodstring
The algorithm used to process the code challenge. The value should be S256

cURL
Node.js
Python
Go
Java

curl --request GET \
  --url 'https://$env_url/oauth/authorize
  ?client_id=skc_12344
  &redirect_uri=https%3A%2F%2Fmysaasapp.com%2Fredirect_uri
  &response_type=code
  &state=hf68uyjh2189iuhj56789
  &scope=openid email profile'

import { ScalekitClient } from '@scalekit-sdk/node';

// Initialize the SDK client
const scalekit = new ScalekitClient(
  '<SCALEKIT_ENVIRONMENT_URL>',
  '<SCALEKIT_CLIENT_ID>',
  '<SCALEKIT_CLIENT_SECRET>',
);

const options = {};

// Option 1: Authorization URL with the organization ID
options["organizationId"] = 'org_15421144869927830';

// Option 2: Authorization URL with login hint
options.connectionId = 'conn_15696105471768821';

// Option 3: Authorization URL with login hint
options.loginHint = 'user@example.com';

const authorizationURL = scalekit.getAuthorizationUrl(
  redirectUrl,
  options,
);

from scalekit import ScalekitClient, AuthorizationUrlOptions, CodeAuthenticationOptions

# Initialize the SDK client
scalekit_client = ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
)

options = AuthorizationUrlOptions()


# Option 1: Authorization URL with the organization ID
options.organization_id = 'org_15421144869927830'

# Option 2: Authorization URL with login hint
options.login_hint = 'user@example.com'

# Option 3: Authorization URL with the connection ID
options.connection_id = 'conn_15696105471768821'

authorization_url = scalekit_client.get_authorization_url(
  redirect_uri=<redirect_uri>,
  options=options
)

# Redirect the user to this authorization URL

import (
  "github.com/scalekit/scalekit-sdk-go"
)

func main() {
  // Initialize the SDK client
  sc := scalekit.NewScalekitClient(
    "<SCALEKIT_ENVIRONMENT_URL>",
    "<SCALEKIT_CLIENT_ID>",
    "<SCALEKIT_CLIENT_SECRET>"
  )

  options := scalekit.AuthorizationUrlOptions{}

  // Option 1: Authorization URL with the organization ID
  options.OrganizationId = "org_15421144869927830"

  // Option 2: Authorization URL with the connection ID
  options.ConnectionId = "conn_15696105471768821"

  // Option 3: Authorization URL with Login Hint
  // User's email domain detects the correct enterprise SSO connection.
  options.LoginHint = "user@example.com"

  authorizationURL := sc.GetAuthorizationUrl(
    redirectUrl,
    options,
  )
   // Next step is to redirect the user to this authorization URL
}

// Redirect the user to this authorizationURL

package com.scalekit;

import com.scalekit.ScalekitClient;
import com.scalekit.internal.http.AuthorizationUrlOptions;

public class Main {

  public static void main(String[] args) {
    // Initialize the SDK client
    ScalekitClient scalekitClient = new ScalekitClient(
      "<SCALEKIT_ENVIRONMENT_URL>",
      "<SCALEKIT_CLIENT_ID>",
      "<SCALEKIT_CLIENT_SECRET>"
    );
    AuthorizationUrlOptions options = new AuthorizationUrlOptions();
    // Option 1: Authorization URL with the organization ID
    options.setOrganizationId("org_13388706786312310");
    // Option 2: Authorization URL with the connection ID
    options.setConnectionId("con_13388706786312310");
    // Option 3: Authorization URL with Login Hint
    // User's email domain detects the correct enterprise SSO connection.
    options.setLoginHint("user@example.com");
    try {
      String url = scalekitClient
        .authentication()
        .getAuthorizationUrl(redirectUrl, options)
        .toString();
    } catch (Exception e) {
      System.out.println(e.getMessage());
    }
  }
}
// Redirect the user to this authorizationURL

Response

User will be redirected to the appropriate Identity provider's login page based on either organization_id, or connection_id or domain.

Token URL

The code provided to the Redirect URI. Code can be exchanged for a ID Token containing the user details using the Token URL.

Parameters
codestringrequired
The code received by the Redirect URI as part of the Authentication Response.
redirect_uristringrequired
The redirect URI where this code was received. This will used to validate the code to make the code was infact generated for this redirect_uri.
client_idstringrequired
Unique client ID that represents your application.
client_secretstringrequired
The client secret to authorize the client.
grant_typestring
Grant Type must be authorization_code.
code_verifierstring
Used in PKCE flow, code_verifier is derived from the code_challenge presented at the Authorization Endpoint

cURL
Node.js
Python
Go
Java

curl --request POST \
  --url 'https://$env_url/oauth/token
  ?code=jhasd72
  &redirect_uri=https%3A%2F%2Fmysaasapp.com%2Fredirect_uri
  &client_id=skc_12344
  &client_secret=skc_prod_12441kjasad
  &grant_type=authorization_code'

import { ScalekitClient } from "@scalekit-sdk/node";

const scalekit = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

// Handle the oauth redirect
const { code, error, error_description } = req.query;
if (error) {
  // Handle error
  return throw new Error(error_description);
}

// Fetch user details by exchanding the code received in the request params
const { user } = await scalekit.authenticateWithCode(
  code,
  <redirectUri>
);

from scalekit import ScalekitClient, AuthorizationUrlOptions, CodeAuthenticationOptions

scalekit_client = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

# Handle oauth redirect_url, fetch code and error_description from request params
code = request.args.get('code')
error = request.args.get('error')
error_description = request.args.get('error_description')

if error:
    raise Exception(error_description)

result = scalekit_client.authenticate_with_code(
  code,
  <redirect_uri>
)
# result.user has the authenticated user's details
user_email = result.user.email

# Create a session and redirect the user to your dashboard

import (
  "github.com/scalekit/scalekit-sdk-go"
)
sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

// Handle the oauth redirect
code := r.URL.Query().Get("code")
err := r.URL.Query().Get("error")
errorDescription := r.URL.Query().Get("error_description")
if err != "" {
  return errors.New(errorDescription)
}

// Fetch user details by exchanding the code received in the request params
user, err := sc.AuthenticateWithCode(
  code,
  <redirectUri>
)
// `user` has the authenticated user's details
userEmail := user.Email

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

String code = request.getParameter("code");
String error = request.getParameter("error");
String errorDescription = request.getParameter("error_description");

if(error != null && !error.isEmpty()) {
    // Handle errors
    return;
}
try {
    AuthenticationResponse res = scalekitClient.authentication().authenticateWithCode(code, redirectUrl);
    // res.getIdTokenClaims() has the authenticated user's details
    String userEmail = res.getIdTokenClaims().getEmail();

} catch (Exception e) {
    // Handle errors
}

Response

{
  "access_token": "ey ... vPnyWBQ",
  "expires_in": 899,
  "id_token": "eyJhbGc ... ar79GwZg",
  "token_type": "Bearer"
}

Organization

Organization represents a customer or a tenant of your application. Use this to create enterprise Single Sign-on connections or Admin Portal links for your customers.

Endpoints

get/api/v1/organizations post/api/v1/organizations get/api/v1/organizations/{id}delete/api/v1/organizations/{id}patch/api/v1/organizations/{id}

The Organization Object

Attributes
idstring
Unique ID of the organization
display_namestring
Display Name of the Organization
external_idstring
Unique ID of this organization according to your system. You can store your unique ID for this organization in Scalekit's system and later use this to fetch Organization and Connection details. This is helpful if you don't want to persist Scalekit's Unique Identifiers in your database
metadatamap
Set of key-value pairs that you can attach to the Organization object. This can be useful for storing additional information about the Organization in a structured format.
region_codeenum
Region in which this organization data is stored in. By default, the environment's region_code is used to store this organization's data
Possible values
US
EU
create_timestring
Timestamp at which this organization record was created in ISO 8601 format
update_timestring
Timestamp at which this organization record was last updated in ISO 8601 format

Organization Object

{
    "id": "org_2123312131125533",
    "display_name": "Acme Corp",
    "create_time": "2024-01-05T14:48:00.000Z",
    "external_id": "my_unique_id",
    "metadata": {
      "someKey": "somevalue"
    },
    "region_code": "US",
    "update_time": "…"
}

List Organizations

List all Organizations in the Environment. The results are paginated. The response contains page_token that can be used to access the next page of results.

Parameters
page_sizeintegerrequired
Number of results to be returned. Max supported page_size is 30
page_tokenstring

cURL
Node.js
Python
Go
Java

curl --request GET \
  --url 'https://$env_url/api/v1/organizations'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const organizations = await sc.organization.listOrganization({
  pageSize: 10,
});

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

options = ListOrganizationOptions()
options.page_size = 10

organizations = sc.organization.list_organizations(
  options=options
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

organizations, err := sc.Organization.ListOrganizations(
  ctx,
  &scalekit.ListOrganizationOptions{
    PageSize: 10,
  }
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

ListOrganizationsResponse organizations = scalekitClient
  .organizations()
  .listOrganizations(10, "");

Response

{
  "next_page_token": "…",
  "organizations": [
    {
      "create_time": "2024-01-05T14:48:00.000Z",
      "display_name": "Acme Corp",
      "external_id": "my_unique_id",
      "id": "org_2123312131125533",
      "metadata": {
        "someKey": "…"
      },
      "region_code": "US",
      "update_time": "…"
    }
  ],
  "total_size": 1
}

Create Organization

Creates an Organization. An Organization represents a tenant in the your application

Parameters
organizationrequired
Organization details

cURL
Node.js
Python
Go
Java

curl --location 'https://$ENV_URL/api/v1/organizations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "display_name": "<string>",
  "external_id": "<string>",
  "metadata": {
    "esse47": "<string>"
  }
}'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const organization = await sc.organization.createOrganization(name, {
  externalId: 'externalId',
});

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)
options = CreateOrganizationOptions()
options.external_id = "externalId"
organization = sc.organization.create_organization(
  name,
  options=options
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

organization, err := sc.Organization.CreateOrganization(
  ctx,
  name,
  scalekit.CreateOrganizationOptions{
    ExternalID: "externalId",
  },
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

CreateOrganization createOrganization =
  CreateOrganization.newBuilder().setDisplayName("Test Org").build();

Organization createdOrganization = scalekitClient
  .organizations()
  .create(createOrganization);

Response

{
    "create_time": "2024-01-05T14:48:00.000Z",
    "display_name": "Acme Corp",
    "external_id": "my_unique_id",
    "id": "org_2123312131125533",
    "metadata": {
        "someKey": "…"
    },
    "region_code": "US",
    "update_time": "…"
}

Get Organization

Parameters
idstringrequired
Id of the Org to update
external_idstring
External Id of the Org to update

cURL
Node.js
Python
Go
Java

curl --request GET \
  --url 'https://$env_url/api/v1/organizations/{id}'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const organization = await sc.organization.getOrganization(organization_id);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

organization = sc.organization.get_organization(
  organization_id
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

organization, err := sc.Organization.GetOrganization(
  ctx,
  organizationId
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

Organization organization = scalekitClient
  .organizations()
  .getById(organizationId);

Response

{
  "create_time": "2024-01-05T14:48:00.000Z",
  "display_name": "Acme Corp",
  "external_id": "my_unique_id",
  "id": "org_2123312131125533",
  "metadata": {
    "someKey": "…"
  },
  "region_code": "US",
  "update_time": "…"
}

Update Organization

Parameters
idstringrequired
Id of the Org to update
organizationrequired
external_idstring
External Id of the Org to update

cURL
Node.js
Python
Go
Java

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{id}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "display_name": "<string>",
  "external_id": "<string>",
  "metadata": {
    "culpa_561": "<string>"
  }
}'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const organization = await sc.organization.updateOrganization(organization_id, {
  displayName: 'displayName',
  externalId: 'externalId',
});

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

organization = sc.organization.update_organization(organization_id, {
  display_name: "display_name",
  external_id: "external_id"
})

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

organization, err := sc.Organization.UpdateOrganization(
  ctx,
  organizationId,
  &scalekit.UpdateOrganization{
    DisplayName: "displayName",
    ExternalId: "externalId",
  },
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

UpdateOrganization updateOrganization =
  UpdateOrganization.newBuilder()
    .setDisplayName("Updated Organization Name")
    .build();

Organization updatedOrganizationById = scalekitClient
  .organizations()
  .updateById(organizationId, updateOrganization);

Response

{
    "create_time": "2024-01-05T14:48:00.000Z",
    "display_name": "Acme Corp",
    "external_id": "my_unique_id",
    "id": "org_2123312131125533",
    "metadata": {
        "someKey": "…"
    },
    "region_code": "US",
    "update_time": "…"
}

Delete Organization

Parameters
idstringrequired
Id of the Org to update
external_idstring
External Id of the Org to update

cURL
Node.js
Python
Go
Java

curl --location --request DELETE 'https://$ENV_URL/api/v1/organizations/{id}' \
--header 'Accept: application/json'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

await sc.organization.deleteOrganization(organizationId);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

sc.organization.delete_organization(organization_id)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

err := sc.Organization.DeleteOrganization(
  ctx,
  organizationId
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

scalekitClient.organizations().deleteById(organizationId);

Response

{}

Admin Portal

Endpoints

put/api/v1/organizations/{id}/portal_links

Generate Portal link

Generates a Admin Portal link. The Admin Portal will be used by the IT Admins to create and manage the SSO connection in their Org. The link generated via API will be valid for 1 week.

Parameters
idstringrequired
Organization ID

cURL
Node.js
Python
Go
Java

curl --location --request PUT 'https://$ENV_URL/api/v1/organizations/{id}/portal_links' \
--header 'Accept: application/json'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const link = await sc.organization.generatePortalLink(organization_id);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

link = sc.organization.generate_portal_link(
  organization_id
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

link, err := sc.Organization.GeneratePortalLink(
  ctx,
  organizationId
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

Link response = scalekitClient
  .organizations()
  .generatePortalLink(organizationId);

Response

{
  "link": {
    "id": "lnk_123123123123123",
    "location": "https://scalekit.com/portal/lnk_123123123123123",
    "expire_time": "2024-02-06T14:48:00.000Z"
  }
}

Connection

Endpoints

get/api/v1/connections get/api/v1/organizations/{organization_id}/connections/{id}patch/api/v1/organizations/{organization_id}/connections/{id}:disable patch/api/v1/organizations/{organization_id}/connections/{id}:enable

The Connection Object

Attributes
idstring
Unique ID of the Connection
organization_idstring
Organization ID to which this connection belongs to.
providerenum
Possible values
OKTA
GOOGLE
MICROSOFT_AD
AUTH0
ONELOGIN
PING_IDENTITY
JUMPCLOUD
CUSTOM
statusenum
Possible values
DRAFT
IN_PROGRESS
COMPLETED
enabledboolean
typeenum
Possible values
OIDC
SAML
saml_configobject
Child Attributes
sp_entity_idstring
sp_assertion_urlstring
sp_metadata_urlstring
idp_entity_idstring
idp_sso_urlstring
idp_metadata_urlstring
idp_certificatesarray object
Child Attributes
certificatestring
expiry_timestring
issuerstring
create_timestring
idp_sso_request_bindingenum
Possible values
POST
REDIRECT
idp_slo_urlstring
idp_slo_request_bindingenum
Possible values
POST
REDIRECT
saml_signing_optionenum
Possible values
NO_SIGNING
SAML_ONLY_RESPONSE_SIGNING
SAML_ONLY_ASSERTION_SIGNING
SAML_RESPONSE_ASSERTION_SIGNING
assertion_encryptedboolean
want_request_signedboolean
oidc_configobject
Child Attributes
authorize_uristring
token_uristring
discovery_endpointstring
user_info_uristring
jwks_uristring
issuerstring
redirect_uristring
client_idstring
client_secretstring
scopesstring
pkce_enabledboolean
token_auth_typestring
create_timestring
Timestamp at which this organization record was created in ISO 8601 format
update_timestring
Timestamp at which this organization record was last updated in ISO 8601 format

Connection Object

{
    "id": "conn_2123312131125533",
    "organization_id": "org_1232434",
    "provider": "OKTA",
    "type": "SAML",
    "status": "COMPLETED",
    "enabled": true,
    "debug_enabled": false,
    "configuration_type": "MANUAL",
    "saml_config":{
        "sp_entity_id": "https://yourapp.com/service/saml",
        "sp_assertion_url": "https://youridp.com/service/saml/assertion",
        "sp_metadata_url": "https://youridp.com/service/saml/metadata",
        "idp_metadata_url": "https://youridp.com/service/idp/metadata",
        "idp_sso_url": "https://youridp.com/sso/saml",
    }
    "attribute_mapping":{
        "email": "email",
        "family_name": "lastName",
        "given_name": "firstName",
        "sub": "nameid",
    }
    "create_time": "2024-01-05T14:48:00.000Z",
}

List Connections

Get a filtered list of connections

Parameters
organization_idstring
Organization ID for the Connection
domainstring
Email domain associated with this connection. If domain is not empty it would return connections that are available to email domain by matching the organization associated to the domain
includestring

cURL
Node.js
Python
Go
Java

curl --request GET \
  --url 'https://$env_url/api/v1/connections'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const connections = await sc.connection.listConnections(organizationId);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

connections = sc.connection.list_connections(
  organization_id
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

connections, err := sc.Connection.ListConnections(
  ctx,
  organizationId
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<ENVIRONMENT_URL>",
  "<CLIENT_ID>",
  "<CLIENT_SECRET>"
);

ListConnectionsResponse response = scalekitClient
  .connections()
  .listConnectionsByOrganization(organizationId);

Response

{
  "connections": [
    {
      "id": "conn_2123312131125533",
      "organization_id": "org_1232434",
      "provider": "OKTA",
      "type": "SAML",
      "status": "COMPLETED",
      "enabled": true,
      "debug_enabled": false,
      "configuration_type": "MANUAL",
      "saml_config":{
        "sp_entity_id": "https://yourapp.com/service/saml",
        "sp_assertion_url": "https://youridp.com/service/saml/assertion",
        "sp_metadata_url": "https://youridp.com/service/saml/metadata",
        "idp_metadata_url": "https://youridp.com/service/idp/metadata",
        "idp_sso_url": "https://youridp.com/sso/saml",
      }
      "attribute_mapping":{
        "email": "email",
        "family_name": "lastName",
        "given_name": "firstName",
        "sub": "nameid",
      }
      "create_time": "2024-01-05T14:48:00.000Z",
    }
  ],
}

Get Connection

Get Connection details

Parameters
organization_idstringrequired
Organization ID for the Connection.
idstringrequired
Connection ID. Unique ID for the connection

cURL
Node.js
Python
Go
Java

curl --location 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}' \
--header 'Accept: application/json'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

const connection = await sc.connection.getConnection(
  organizationId,
  connectionId
);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

connection = sc.connection.get_connection(
  organization_id,
  connection_id,
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

connection, err := sc.Connection.GetConnection(
  ctx,
  organizationId,
  connectionId,
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

Connection connection = client
  .connections()
  .getConnectionById(connectionId, organizationId);

Response

{
  "id": "conn_2123312131125533",
  "organization_id": "org_1232434",
  "provider": "OKTA",
  "type": "SAML",
  "status": "COMPLETED",
  "enabled": true,
  "debug_enabled": false,
  "configuration_type": "MANUAL",
  "saml_config":{
    "sp_entity_id": "https://yourapp.com/service/saml",
    "sp_assertion_url": "https://youridp.com/service/saml/assertion",
    "sp_metadata_url": "https://youridp.com/service/saml/metadata",
    "idp_metadata_url": "https://youridp.com/service/idp/metadata",
    "idp_sso_url": "https://youridp.com/sso/saml",
  }
  "attribute_mapping":{
    "email": "email",
    "family_name": "lastName",
    "given_name": "firstName",
    "sub": "nameid",
  }
  "create_time": "2024-01-05T14:48:00.000Z",
}

Disable a Connection for an Organization

Disable a SSO Connection

Parameters
organization_idstringrequired
Organization ID for the Connection.
idstringrequired
Connection ID. Unique ID for the connection

cURL
Node.js
Python
Go
Java

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}:disable' \
--header 'Accept: application/json'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

await sc.connection.disableConnection(organizationId, connectionId);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

sc.connection.disable_connection(
  organization_id,
  connection_id
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

err := sc.Connection.DisableConnection(
  ctx,
  organizationId,
  connectionId,
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

ToggleConnectionResponse response = client
  .connections()
  .disableConnection(connectionId, organizationId);

Response

{
  "enabled": false,
  "error_message": ""
}

Enable a Connection for an Organization

Enable a SSO Connection

Parameters
organization_idstringrequired
Organization ID for the Connection.
idstringrequired
Connection ID. Unique ID for the connection

cURL
Node.js
Python
Go
Java

curl --location --request PATCH 'https://$ENV_URL/api/v1/organizations/{organization_id}/connections/{id}:enable' \
--header 'Accept: application/json'

const sc = new ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
);

await sc.connection.enableConnection(organizationId, connectionId);

sc = ScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

sc.connection.enable_connection(
  organization_id,
  connection_id,
)

sc := scalekit.NewScalekitClient(
  <SCALEKIT_ENVIRONMENT_URL>,
  <SCALEKIT_CLIENT_ID>,
  <SCALEKIT_CLIENT_SECRET>
)

err := sc.Connection.EnableConnection(
  ctx,
  organizationId,
  connectionId,
)

ScalekitClient scalekitClient = new ScalekitClient(
  "<SCALEKIT_ENVIRONMENT_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>"
);

ToggleConnectionResponse response = client
  .connections()
  .enableConnection(connectionId, organizationId);

Response

{
  "enabled": true,
  "error_message": ""
}