Tenants registry API

1. Introduction

This web API is available only on the multitenant edition of the Connect2id server. It facilitates the registration of OpenID Connect providers / OAuth 2.0 authorisation servers as isolated tenants with their own issuer URL and configuration.

2. Web API overview

Resources
Representations Errors

3. Resources

3.1 /tenants/rest/v1

Use this resource to create or retrieve tenants.

3.1.1 POST

Creates a new tenant.

Header parameters:

  • Authorization Must specify the configured bearer access token for this web API.

  • Content-Type Must be set to application/json.

Body:

  • A JSON object representation of the tenant.

Success:

  • Code: 201

Errors:

Example request to register a new tenant with ID t123:

GET /tenants/rest/v1/ HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "tid"   : "t123",
  "props" : { "op.issuer"         : "https://t123.c2id.com",
              "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
              "op.authz.endpoint" : "https://t123.c2id.com/login",
              "..."               : "..." }
}

Example response indicating successful creation:

HTTP/1.1 201 Created

3.1.2 GET

Retrieves all tenants in a JSON array.

Header parameters:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON array representing the individual tenants, empty array if none were found.

Errors:

3.2 /tenants/rest/v1/{tid}

Use this resource to retrieve or delete an individual tenant.

3.2.1 GET

Retrieves a tenant.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} The tenant.

Errors:

Example request to retrieve the tenant with ID t123:

GET /tenants/rest/v1/t123 HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "tid"   : "t123",
  "props" : { "op.issuer"         : "https://t123.c2id.com",
              "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
              "op.authz.endpoint" : "https://t123.c2id.com/login",
              "..."               : "..." }
}

3.2.2 DELETE

Deletes a tenant.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Success:

  • Code: 204

Errors:

Example request to delete the tenant with ID t123:

DELETE /tenants/rest/v1/t123 HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response indicating successful deletion:

HTTP/1.1 204 No Content

3.3 /tenants/rest/v1/{tid}/props

Use this resource to retrieve or update a tenant's configuration properties.

3.3.1 GET

Retrieves a tenant's configuration properties.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Success:

Errors:

Example request to retrieve the configuration properties of tenant with ID t123:

GET /tenants/rest/v1/t123/props HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "op.issuer"         : "https://t123.c2id.com",
  "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
  "op.authz.endpoint" : "https://t123.c2id.com/login",
  "..."               : "..."
}

3.3.2 PUT

Updates a tenant's configuration properties.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Body:

Success:

  • Code: 204

Errors:

Example request to update the configuration properties of tenant with ID t123:

PUT /tenants/rest/v1/t123/props HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "op.issuer"         : "https://t123.c2id.com",
  "jose.jwkSet"       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
  "op.authz.endpoint" : "https://t123.c2id.com/login",
  "..."               : "..."
}

3.4 /tenants/rest/v1/count

This resource keeps count of the tenants.

3.5.1 GET

Returns the current total tenant count.

Header parameters:

Success:

  • Code: 200

  • Content-Type: text/plain

  • Body: {integer} The total tenant count, zero if none.

Errors:

Example request to retrieve the total tenant count:

GET /tenants/rest/v1/count HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Example response indicating 10 registered tenants:

HTTP/1.1 200 OK
Content-Type: text/plain

10

4. Representations

4.1 Tenant

OpenID Connect provider / OAuth 2.0 Authorisation Server tenant.

JSON object members:

4.2 Configuration properties

Tenant configuration, as Java property name / value pairs contained in a JSON object.

All property values must be put in strings, including values that are integers, booleans and JSON objects.

The following tenant specific configuration properties are supported at present (all that are required must be set):

Example configuration properties:

{
  "op.issuer"                         : "https://t123.c2id.com",
  "jose.jwkSet"                       : "eyAia2V5cyIgOiBbIHsgImt0eSIgOiAiUl...",
  "op.authz.endpoint"                 : "https://t123.c2id.com/login",
  "op.policy"                         : "https://t123.c2id.com/policy",
  "op.tos"                            : "https://t123.c2id.com/terms-of-service",
  "op.serviceDocs"                    : "https://t123.c2id.com/service-docs",
  "sessionStore.apiAccessTokenSHA256" : "cca68b8b82bcf0b96cb826199429e50cd9...",
  "sessionStore.maxLifetime"          : "20160",
  "sessionStore.authLifetime"         : "10080",
  "sessionStore.maxIdleTime"          : "1440",
  "sessionStore.quotaPerSubject"      : "5",
  "..."                               : "..."
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON: Unexpected token foo at position 3."
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error"             : "missing_token",
  "error_description" : "Unauthorized: Missing Bearer access token"
}

404 Not Found

The requested resource doesn't exist.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Check the logs for details"
}