KeyRunner SCIM Integration Guide

Overview

KeyRunner supports SCIM (System for Cross-domain Identity Management) to automate user lifecycle management. This includes user creation, updates, and deletions. The SCIM API allows your organization, acting as the Identity Provider (IdP), to manage users in KeyRunner, which acts as the Service Provider (SP).

SCIM API Base URL

The SCIM API base URL for KeyRunner is:

https://scim.keyrunner.app/scim/v2

This URL is used to access the SCIM API endpoints for managing users and other operations.

---

Authentication

To interact with KeyRunner’s SCIM API, you will need an API Key for authentication. The API Key must be included in the Authorization header as a Bearer token in every request.

Example:

Authorization: Bearer ProjectId:AccessKey

Email : Contact@keyrunner.app to get a API Key

---

SCIM Operations

KeyRunner supports the following SCIM operations for managing user resources:

1. Load all users

curl -X GET "https://scim.keyrunner.app/scim/v2/Users?filter=string&startIndex=0&count=0" \
  -H "Authorization: Bearer <AccessKey>"

2. Retrieve a User

Fetch an existing user’s details by using their unique user ID.

curl -X GET "https://scim.keyrunner.app/scim/v2/Users/{userId}" \
  -H "Authorization: Bearer <AccessKey>"

3. Update a User

Update the details of an existing user, such as their name or email address.

curl -X PUT "https://scim.keyrunner.app/scim/v2/Users/{userId}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AccessKey>" \
  -d '{
  "userId": "string",
  "displayName": "string",
  "emails": [
    {
      "value": "string",
      "primary": true,
      "type": "string"
    }
  ],
  "active": true,
  "name": {
    "givenName": "string",
    "familyName": "string",
    "middleName": "string"
  },
  "userName": "string",
  "attributes": {}
}'

4. Delete a User

Remove a user from KeyRunner by their unique user ID.

curl -X DELETE  "https://scim.keyrunner.app/scim/v2/Users/{userId}" \
  -H "Authorization: Bearer <AccessKey>"

---

SCIM User Model

KeyRunner follows the SCIM 2.0 standard for user resources. The following are key attributes for the User resource:

• userName: The unique username for the user, typically their email address.
• name: The user's full name.
  • givenName: The first name of the user.
  • familyName: The last name of the user.
• emails: A list of email addresses associated with the user.
  • value: The email address.
  • type: The type of email (e.g., "work").
  • primary: Boolean indicating whether this is the user's primary email address.

For full SCIM attribute details, refer to the SCIM 2.0 specification.

---

Error Handling

KeyRunner’s SCIM API uses standard HTTP status codes to communicate the result of a request:

• 200 OK: The request was successful, and the response contains the requested data.
• 201 Created: A new resource has been created successfully.
• 400 Bad Request: The request was invalid or missing required data.
• 401 Unauthorized: Invalid or missing authentication credentials (API Key).
• 404 Not Found: The requested resource was not found.
• 500 Internal Server Error: A server-side error occurred.

---

Rate Limiting

KeyRunner may apply rate limits to SCIM API requests to ensure fair use and prevent overload. If you exceed the rate limit, you will receive a 429 Too Many Requests response.

---

Troubleshooting

Common Issues:

• Invalid Authentication: Make sure that the correct API Key is included in the Authorization header.
• Missing or Invalid Data: Ensure that the required fields like userName, name, etc., are included and correctly formatted in the request.
• Incorrect Endpoints: Verify that you are using the correct SCIM endpoint for the intended operation, such as GET /Users/{userId} to retrieve user data.

If the issues persist, please contact KeyRunner Support.