index.adoc

Authorization Server API Reference

Table of Contents

• Overview
  • HTTP verbs
  • HTTP status codes
  • Errors
  • Resources
    • Users
      • Retrieve User List
      • Retrieve Single User
      • Create User
      • Update User
      • Delete User
    • Groups
      • Retrieve Group List
      • Retrieve Single Group
      • Create Group
      • Delete Group
      • Add a member to Group
      • Remove a member from Group
    • Registered Clients
      • Retrieve Client List
      • Retrieve Single Client
      • Register new Client
      • Update Client
      • Delete Client

Overview

HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb	Usage
GET	Used to retrieve a resource
POST	Used to create a new resource
PATCH	Used to update an existing resource, including partial updates
DELETE	Used to delete an existing resource

HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code	Usage
200 OK	The request completed successfully
201 Created	A new resource has been created successfully. The resource’s URI is available from the response’s Location header
204 No Content	An update to an existing resource has been applied successfully
400 Bad Request	The request was malformed. The response body will include an error providing further information
404 Not Found	The requested resource did not exist

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Resources

Users

User model is aligned with SCIM2 Core.

User Rest API is aligned with SCIM2 Protocol.

Retrieve User List

A GET request is used to retrieve a list of all existing users.

operation::getAllUsers[snippets='http-request,httpie-request,curl-request,http-response']

Retrieve Single User

A GET request is used to retrieve a single user.

operation::getUser[snippets='http-request,httpie-request,curl-request,http-response']

Create User

A POST request is used to create a new user.

operation::createUser[snippets='http-request,httpie-request,curl-request,http-response']

Update User

A PUT request is used to update a user.

operation::updateUser[snippets='http-request,httpie-request,curl-request,http-response']

Delete User

A DELETE request is used to delete a user.

operation::deleteUser[snippets='http-request,httpie-request,curl-request,http-response']

Groups

Group model is aligned with SCIM2 Core.

Group Rest API is aligned with SCIM2 Protocol.

Retrieve Group List

A GET request is used to retrieve a list of all existing groups.

operation::getAllGroups[snippets='http-request,httpie-request,curl-request,http-response']

Retrieve Single Group

A GET request is used to retrieve a single group.

operation::getGroup[snippets='http-request,httpie-request,curl-request,http-response']

Create Group

A POST request is used to create a new group.

operation::createGroup[snippets='http-request,httpie-request,curl-request,http-response']

Delete Group

A DELETE request is used to delete a group.

operation::deleteGroup[snippets='http-request,httpie-request,curl-request,http-response']

Add a member to Group

A PUT request is used to add a member to a group.

operation::addMemberToGroup[snippets='http-request,httpie-request,curl-request,http-response']

Remove a member from Group

A PUT request is used to remove a member from a group.

operation::addMemberToGroup[snippets='http-request,httpie-request,curl-request,http-response']

Registered Clients

Registered clients are required to configure valid clients interacting with the authorization server. Currently, only static is supported. Dynamic registration is not yet supported.

Table 1. Registered Client Attributes

Name	Description
clientId	Client ID
clientSecret	Client secret, only needed for confidential clients
confidential	true=Confidential, false=Public client. If Public Client it requires PKCE but no clientSecret, Confidential Client requires clientSecret
accessTokenFormat	JWT=JSON Web Token format, OPAQUE=Opaque (reference) Token format
grantTypes	Valid grant types: AUTHORIZATION_CODE,PASSWORD,CLIENT_CREDENTIALS,REFRESH_TOKEN,TOKEN_EXCHANGE
redirectUris	List of valid redirect URIs (no wildcards allowed)
corsUris	List of valid CORS URIs (no wildcards allowed)

Retrieve Client List

A GET request is used to retrieve a list of all existing clients.

operation::getAllClients[snippets='http-request,httpie-request,curl-request,http-response']

Retrieve Single Client

A GET request is used to retrieve a single client.

operation::getClient[snippets='http-request,httpie-request,curl-request,http-response']

Register new Client

A POST request is used to register a new client.

operation::createClient[snippets='http-request,httpie-request,curl-request,http-response']

Update Client

A PUT request is used to update a client.

operation::updateClient[snippets='http-request,httpie-request,curl-request,http-response']

Delete Client

A DELETE request is used to delete a client.

operation::deleteClient[snippets='http-request,httpie-request,curl-request,http-response']