Use Case: Build SSO Integrations

Create and configure SAML or OIDC applications, then grant access to users and user groups.

Step 1: Discover application templates (SAML)#

Overview#

JumpCloud provides pre-built SAML templates (Slack, AWS, Salesforce, and others). Fetch available templates to obtain the name value and required config fields before creating an application.

Requirements#

Item	Required	Notes
API key `x-api-key`	Yes	Scopes: `applicationtemplates`, `applicationtemplates.readonly`

Endpoint#

Reference: List Application Templates

GET https://console.jumpcloud.com/api/application-templates

To inspect a single template:

Reference: Get an Application Template

GET https://console.jumpcloud.com/api/application-templates/{id}

Request#

curl -X GET https://console.jumpcloud.com/api/application-templates \
  -H 'Accept: application/json' \
  -H 'x-api-key: {API_KEY}'

Successful response#

HTTP 200 — paginated list of templates. Each record includes name, displayName, and default config field definitions for the service provider.

Example (abbreviated):

{
  "results": [
    {
      "_id": "5be9fb4ddb01290001e85120",
      "name": "slack",
      "displayName": "Slack",
      "config": { }
    }
  ],
  "totalCount": 1
}

Step 2: Create a SAML application (v1)#

Overview#

Create an SSO/SAML application in a single request. The v1 Applications API is the public, documented path for SAML configuration. Required SP settings are passed in the config object; field shapes vary by template.

Requirements#

Item	Required	Notes
API key `x-api-key`	Yes	Scopes: `applications`, `applications.create`
`name`	Yes	Template name from Step 1 (for example `slack`)
`displayLabel`	Yes	Label shown in the admin console
`displayName`	Yes	Name shown in the user portal
`ssoUrl`	Yes	Unique SSO URL slug for the application
`config`	Yes (SAML)	SP settings such as `acsUrl`, `spEntityId`, signing options

Endpoint#

Reference: Create an Application

POST https://console.jumpcloud.com/api/applications

Request#

curl -X POST https://console.jumpcloud.com/api/applications \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "name": "slack",
    "displayName": "Slack",
    "displayLabel": "Slack SSO",
    "ssoUrl": "slack-engineering",
    "config": {
      "acsUrl": { "value": "https://example.slack.com/sso/saml" },
      "spEntityId": { "value": "https://example.slack.com" },
      "signResponse": { "value": true }
    }
  }'

Successful response#

HTTP 200

{
  "_id": "5be9fb4ddb01290001e85110",
  "name": "slack",
  "displayName": "Slack",
  "displayLabel": "Slack SSO",
  "ssoUrl": "slack-engineering",
  "active": true
}

Save _id for Step 3.

Step 3: Control user and group access#

Overview#

Associate user groups or individual users with the application. Only bound users and members of bound groups see the app in the user portal and can initiate SSO.

Supported association targets: user_group, user.

Requirements#

Item	Required	Notes
API key `x-api-key`	Yes	Scopes: `associations.applications`, `associations`
Application ID	Yes	`_id` from Step 2
Target ID	Yes	User Group ID or User ID
`op`	Yes	`"add"` to grant access; `"remove"` to revoke

Endpoint#

Reference: Manage the associations of an Application

POST https://console.jumpcloud.com/api/v2/applications/{application_id}/associations

Request (grant group access)#

curl -X POST https://console.jumpcloud.com/api/v2/applications/{Application_ID}/associations \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "op": "add",
    "type": "user_group",
    "id": "{Group_ID}"
  }'

Request (grant individual user access)#

curl -X POST https://console.jumpcloud.com/api/v2/applications/{Application_ID}/associations \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "op": "add",
    "type": "user",
    "id": "{User_ID}"
  }'

Successful response#

HTTP 204 — no response body.

Step 4: Verify user and group bindings#

Overview#

After granting access in Step 3, list the application's direct associations to confirm the expected users or user groups are bound. The grant endpoint returns HTTP 204 with no body, so this read call is how you validate that bindings took effect.

Filter by association target with the required targets query parameter: user_group or user.

Requirements#

Item	Required	Notes
API key `x-api-key`	Yes	Scopes: `associations.applications`, `associations.applications.readonly`
Application ID	Yes	`_id` from Step 2
`targets`	Yes	`user_group` or `user`

Endpoint#

Reference: List the associations of an Application

GET https://console.jumpcloud.com/api/v2/applications/{application_id}/associations?targets=user_group

Request (list group bindings)#

curl -X GET "https://console.jumpcloud.com/api/v2/applications/{Application_ID}/associations?targets=user_group" \
  -H 'Accept: application/json' \
  -H 'x-api-key: {API_KEY}'

Request (list individual user bindings)#

curl -X GET "https://console.jumpcloud.com/api/v2/applications/{Application_ID}/associations?targets=user" \
  -H 'Accept: application/json' \
  -H 'x-api-key: {API_KEY}'

Successful response#

HTTP 200 — array of direct associations. Each record includes a to object with the bound target's type and id.

Example (abbreviated):

[
  {
    "to": {
      "type": "user_group",
      "id": "{Group_ID}"
    }
  }
]

Confirm the id values match the user or user group IDs you added in Step 3.