API Reference

The following is an API reference for the ServiceAuthCentral manage service and the user authentication used by serviceauthcentralweb for the administrative portal. These APIs would not be used by microservices integrating with ServiceAuthCentral and represent the management plane of the system.

Note

For the API reference on the token server and how vend and validate tokens, see the Integration Guide - API Reference page.

POST /v1/token

The POST /v1/token endpoint on the token API is primarily used for the client credentials and jwt bearer grant types as ServiceAuthCentral is primarily used for server-to-server authentication. However, to support the PKCE flow for the serviceauthcentralweb application, the token API also supports the authorization code grant type. This flow is initiated by the serviceauthcentralweb application and then proceeds to the 3rd party application to authenticate the user completing a double OAuth 2.0 authorization process.

GET /login/authorize

The GET /login/authorize endpoint on the token API initiates the OAuth 2.0 authorization process using the PKCE (Proof Key for Code Exchange) flow from the serviceauthcentralweb application and then proceeds a flow for the 3rd party application to authenticate the user.

Request Parameters:

response_type (String): Must be set to code. This indicates that an authorization code is being requested.
client_id (String): The client identifier issued to the client during the registration process.
redirect_uri (String): The URI to which the response will be sent. This must match one of the redirect URIs registered for the client.
code_challenge (String): A challenge derived from the code verifier by using one of the supported transformation methods.
code_challenge_method (String): Must be set to S256. This indicates the method used to derive the code challenge.
state (String): An opaque value used to maintain state between the request and the callback. This value should be used to prevent cross-site request forgery (CSRF) attacks.

Response:

On success, the endpoint will redirect the user to the 3rd party application for user authentication (such as Google or GitHub) using an OAuth 2.0 auth code flow.

GET /login/callback

The GET /login/callback endpoint on the token API handles the callback from the third-party authentication provider after the user has authenticated. This endpoint completes the OAuth 2.0 authorization process by exchanging the authorization code for user information and generating an authorization code for the client application.

Request Parameters:

sessionId (Cookie): The session identifier stored in a secure, HTTP-only cookie. code (String): The authorization code received from the third-party authentication provider. state (String): The state parameter received from the third-party authentication provider. This should match the state parameter sent in the initial authorization request.

Response:

On success, the endpoint will redirect the user back to serviceauthcentralweb completing the original PKCE flow which allows the user to then request a token from the token server that can be used to authenticate to the GraphQL management API.

POST /graphql

The POST /graphql endpoint is the primary endpoint for interacting with the ServiceAuthCentral management API. This endpoint is a GraphQL endpoint that allows for querying and mutating data in the ServiceAuthCentral database.

Query

Field	Type	Description
clients	ClientSummaryConnection	Get a list of clients.
first	Int	The number of items to return starting after the cursor specified by 'after'. Used for forward pagination.
after	String	The cursor after which to return the items. Used for forward pagination.
last	Int	The number of items to return ending before the cursor specified by 'before'. Used for backward pagination.
before	String	The cursor before which to return the items. Used for backward pagination.
client	Client	Get a client by the clientId.
clientId	ID!	The clientId of the client to retrieve.
authorization	Authorization	Get an authorization by the id.
id	ID!	The id of the authorization to retrieve.

Mutation

Field	Type	Description
addClient	Client!	Add a new client.
clientId	String!	The clientId of the new client. Must be globally unique.
description	String!	The description of the client.
availableScopes	[ClientScopeInput]	The list of scopes that this client is aware of and are available to be assigned to an authorized client.
addClientAvailableScope	Response!	Add an additional available scope to an existing client that can be assigned to an authorized client.
clientId	String!	The clientId of the client to add the available scope to.
availableScope	ClientScopeInput!	The available scope to add to the client.
deleteClient	Response!	Delete a client.
clientId	String!	The clientId of the client to delete.
generateClientSecret1	ClientSecret!	Generates a new client secret for a client. This is one of two methods to generate a new client secret, differentiated by their names.
clientId	String!	The clientId of the client to generate a new secret for.
generateClientSecret2	ClientSecret!	Generates a new client secret for a client. This is one of two methods to generate a new client secret, differentiated by their names.
clientId	String!	The clientId of the client to generate a new secret for.
clearClientSecret1	ClientSecret!	Clears the client secret for a client. This is one of two methods to clear the client secret, differentiated by their names.
clientId	String!	The clientId of the client to clear the secret for.
clearClientSecret2	ClientSecret!	Clears the client secret for a client. This is one of two methods to clear the client secret, differentiated by their names.
clientId	String!	The clientId of the client to clear the secret for.
authorizeJwtBearer	Response!	Add a jwt-bearer configuration to a client to use as an authorized user for the client.
clientId	String!	The clientId of the client to authorize for use with jwt-bearer.
jwksUrl	String!	The jwksUrl of the JWT bearer used to validate the JWT.
iss	String!	The `iss` (issuer) claim that must be present in the JWT.
sub	String!	The `sub` (subject) claim that must be present in the JWT.
aud	String!	The `aud` (audience) claim that must be present in the JWT.
deauthorizeJwtBearer	Response!	Deauthorize a jwt-bearer configuration from a client.
clientId	String!	The clientId of the client to deauthorize for use with jwt-bearer.
id	String!	The id of the JWT bearer configuration to deauthorize.
authorize	Response!	Authorize a client to access another client with the authorization.
subject	String!	The clientId of the service that will be granted access to the specified audience.
audience	String!	The clientId of the service that is being accessed by the specified subject.
authorizedScopes	[String]	The scopes that the subject is authorized to access on the audience. The scopes must be a subset of the audience's available scopes.
deauthorize	Response!	Deauthorize a client from accessing another client.
subject	String!	The clientId of the subject that will be deauthorized from the specified audience.
audience	String!	The clientId of the audience that the subject will be deauthorized from.
authorizeAddScope	Response!	Add an authorized scope to an existing authorization.
subject	String!	The clientId of the subject that will be authorized to access the scope.
audience	String!	The clientId of the audience that the subject will be authorized to access the scope on. The scope must be a subset of the audience's available scopes.
authorizedScope	String!	The scope that the subject will be authorized to access on the audience.
authorizeRemoveScope	Response!	Remove an authorized scope from an existing authorization.
subject	String!	The clientId of the subject that will be deauthorized from accessing the scope.
audience	String!	The clientId of the audience that the subject will be deauthorized from accessing the scope on.
authorizedScope	String!	The scope that the subject will be deauthorized from accessing on the audience.

Objects

Authorization

The authorization that allows a client to access another client.

Field	Type	Description
id	ID!	The id of the authorization.
authorizationCreated	String	The date the authorization was created. Returned in ISO-8601 format (yyyy-MM-dd’T’HH:mm:ssZ). The ‘Z’ indicates UTC, which is always used.
subject	Client	The clientId of the subject that is authorized to access the audience.
audience	Client	The clientId of the audience that the subject is authorized to access.
authorizedScopes	[String]	The scopes that the subject is authorized to access on the audience.

Client

The full representation of a client.

Field	Type	Description
clientId	ID!	The clientId of the client.
clientCreated	String	The date the client was created.
description	String	The description of the client.
clientType	String	The type of client.
clientSecret1Set	Boolean	The indicator that the first client secret has been set for the client. The client secret is used to authenticate the client to the authorization server but is stored as a hashed value and cannot be retrieved after it is set.
clientSecret1Updated	String	The time the first client secret was modified. Returned in ISO-8601 format (yyyy-MM-dd'T'HH:mm:ssZ). The 'Z' indicates UTC, which is always used.
clientSecret2Set	Boolean	The indicator that the second client secret has been set for the client. The client secret is used to authenticate the client to the authorization server but is stored as a hashed value and cannot be retrieved after it is set.
clientSecret2Updated	String	The time the second client secret was modified. Returned in ISO-8601 format (yyyy-MM-dd'T'HH:mm:ssZ). The 'Z' indicates UTC, which is always used.
authorizationsAsSubject	[Authorization]	The list of authorizations where the client is the subject.
authorizationsAsAudience	[Authorization]	The list of authorizations where the client is the audience.
availableScopes	[ClientScope]	The list of available scopes that can be assigned to an authorized client.
jwtBearer	[JwtBearer]	The list of jwt-bearer configurations that can be used to authorize the client.
managementPermissions	ClientManagementCapabilities	The client management permissions for the client. These permissions are used to determine what actions can be taken on the client

ClientManagementCapabilities

The client management permissions for a client. These permissions are used to determine what actions can be taken on the client.

Field	Type	Description
canDeleteClient	Boolean!	Indicates if the client can be deleted.
canAddClientSecret	Boolean!	Indicates if the client secret can be added.
canDeleteClientSecret	Boolean!	Indicates if the client secret can be deleted.
canAddClientAuthorization	Boolean!	Indicates a jwt-bearer configuration can be added to the client.
canDeleteClientAuthorization	Boolean!	Indicates a jwt-bearer configuration can be removed from the client.
canAddAvailableScope	Boolean!	Indicates an available scope can be added to the client.
canAddAuthorization	Boolean!	Indicates a client can be authorized to access this client.
canDeleteAuthorization	Boolean!	Indicates a client can be deauthorized from accessing this client.
canAuthorizeAddScope	Boolean!	Indicates a scope can be added.
canAuthorizeRemoveScope	Boolean!	Indicates a scope can be removed.

ClientScope

The scope that can be assigned to an authorized client.

Field	Argument	Type	Description
scope		ID!	The value for the scope.
description		String	The description of the scope.

ClientSecret

The client secret.

Field	Argument	Type	Description
clientSecret		String	The generated client secret. This value is only returned once and cannot be retrieved again.

ClientSummary

The abbreviated representation of a client.

Field	Argument	Type	Description
clientId		ID!	The clientId of the client.
description		String!	The description of the client.

ClientSummaryConnection

A connection object for paginated ClientSummary results.

Field	Argument	Type	Description
edges		[ClientSummaryEdge]	The list of edges, each containing a ClientSummary.
pageInfo		PageInfo!	The page information used for pagination.

ClientSummaryEdge

An edge in a paginated list of ClientSummary objects.

Field	Argument	Type	Description
node		ClientSummary	The ClientSummary node.
cursor		String!	The cursor for use in pagination.

JwtBearer

The jwt-bearer configuration that can be used.

Field	Type	Description
id	ID!	The id of the jwt-bearer configuration.
jwksUrl	String	The jwksUrl of the JWT bearer used to validate the JWT.
iss	String	The iss (issuer) claim that must be present in the JWT.
sub	String	The sub (subject) claim that must be present in the JWT.
aud	String	The aud (audience) claim that must be present in the JWT.

PageInfo

Information about pagination in a connection.

Field	Type	Description
hasNextPage	Boolean!	Indicates if there are more pages to fetch after the current one.
hasPreviousPage	Boolean!	Indicates if there are more pages to fetch before the current one.
startCursor	String	The cursor corresponding to the first node in the current page of results.
endCursor	String	The cursor corresponding to the last node in the current page of results.

Response

The response object for mutations.

Field	Argument	Type	Description
success		Boolean!	The flag indicating if the operation was successful.

Inputs

ClientScopeInput

The input object for adding a new available scope to a client.

Field		Type	Description
scope		ID!	The value for the scope.
description		String	The description of the scope.

Scalars

Boolean

The Boolean scalar type represents true or false.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.