Tenants registry API

1. Overview

This web API is available on the multitenant edition of the Connect2id server. It enables 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:

POST /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",
                "..."               : "..." },
  "enabled" : true
}

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/{tid}/enabled

Use this resource to retrieve or set a tenant's enabled status.

3.4.1 GET

Retrieves a tenant's enabled status.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Success:

  • Code: 200

  • Content-Type: text/plain

  • Body: {true|false} The tenant's enabled status.

Errors:

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

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

Example response:

HTTP/1.1 200 OK
Content-Type: plain/text
Cache-Control: no-store
Pragma: no-cache

true

3.4.2 PUT

Sets a tenant's enabled status.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Body:

  • true to enable the tenant, false to disable it.

Success:

  • Code: 204

Errors:

Example request to disable the tenant with ID t123:

PUT /tenants/rest/v1/t123/enabled HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: plain/text

false

3.5 /tenants/rest/v1/{tid}/metadata

Use this resource to retrieve or update a tenant's optional metadata.

3.5.1 GET

Retrieves a tenant's optional metadata.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} The tenant metadata, empty object if none.

Errors:

Example request to retrieve the metadata of tenant with ID t123:

GET /tenants/rest/v1/t123/metadata 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

{
  "customer_id" : "13",
  "contact"     : "[email protected]",
  "created"     : "2018-06-24"
}

3.5.2 PUT

Updates a tenant's optional metadata.

Path parameters:

  • tid {string} The tenant identifier.

Header parameters:

Body:

  • A JSON object representation of the tenant metadata, empty object if none.

Success:

  • Code: 204

Errors:

Example request to update the metadata of tenant with ID t123:

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

{
  "customer_id" : "13",
  "contact"     : "[email protected]",
  "created"     : "2018-06-24"
}

3.6 /tenants/rest/v1/count

This resource keeps count of the tenants.

3.6.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:

  • tid {string} The tenant identifier. Legal characters are ASCII letters (case insensitive), digits 0 through 9, and the hyphen-minus character (-). Underscore (_) is also allowed but not recommended. This syntax for tenant identifiers allows their use as internet host names and DNS labels according to RFC 1123.

  • props {object} The tenant specific configuration properties.

  • enabled {true|false} If true the tenant is enabled and its OpenID Connect provider / OAuth 2.0 Authorisation server will accept requests. Defaults to true when creating a new tenant.

  • metadata {object} Optional arbitrary metadata for the tenant, omitted if none.

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. Properties that are not recognised will be stored but ignored.

The following tenant specific configuration properties are supported in Connect2id server 7.9+ (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"
}