Your suggested change has been received. Thank you.

close

OAuth 2.0 & OpenID Connect API (v1.0)

Download OpenAPI specification:Download

OAuth 2.0 & OpenID Connect API

OAuth2

OAuth2 endpoints; OAuth allows an application to delegate end-user authentication and authorization to an OAuth Authorization Server (AS)/ OIDC OpenID Connect Provider (OP). Please note that the APIs from this specification can be accessible using either auth2.0 or oauth2 in the URL, so a request to /auth/oauth2.0/v1/authorize and /auth/oauth2/v1/authorize will produce the same result.

OAuth2 authorize endpoint

The authorization endpoint is used to interact with the resource owner and obtain an authorization grant. Use this endpoint to gather authorization from the resource owner when using the following flows: Authorization Code Grant, Authorization Code Grant with PKCE or Implicit Grant.

query Parameters
client_id
required
string

The client ID of the application that asks for authorization.

response_type
string
Enum: "code" "token"

Response type: code or token

redirect_uri
string

Holds a URL. A successful response from this endpoint results in a redirect to this URL.

scope
string

A space-delimited list of permissions that the application requires.

state
string

An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

nonce
string

A value that is returned in the id_token. It is used to mitigate replay attacks.

prompt
string

The supported values are:

  • none The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if an end-user is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing the request. The error code will typically be login_required, interaction_required.
  • login The Authorization Server SHOULD prompt the end-user for reauthentication. If it cannot reauthenticate the end-user, it MUST return an error, typically login_required.
max_age
integer

Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the end-user was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the end-user.

save_consent
boolean

Used to decide whether to save the consent for later or not.

decision
string

Whether the resource owner consents to the requested access, or denies consent. Valid values are, allow or deny.

acr_values
string

Business rules which request for a level of authentication.

code_challenge
string

Using the code_verifier, generate a code_challenge. BASE64URL-ENCODE(SHA256(ASCII("code_verifier" ))) == "code_challenge".

code_challenge_method
string

Method used to generate the code_challenge. It can be either plain or S256.

id_token_hint
string

ID Token previously issued by the Authorization Server being passed as a hint about the end-user’s current or past authenticated session with the Client.

Responses

Response samples

Content type
application/json
{ }

OAuth2 access_token endpoint

This endpoint returns access tokens, ID tokens, and refresh tokens, depending on the request parameters. For password, client credentials, and refresh token flows, calling /auth/oauth2.0/v1/access_token is the only step of the flow. For the authorization code flow, calling /auth/oauth2.0/v1/access_token is the second step of the flow. To make requests to this endpoint, you must include parameters in the request depending on the authentication method that the application is configured with. iWelcome supports the following authentication methods:

  • client_secret_basic, client_secret_post: Use one of these methods when the client has a client secret. Public clients (such as single-page and mobile apps) that can't protect a client secret must use none authentication method.
  • private_key_jwt: This method uses a client-generated JWT signed with an asymmetric key to confirm the client’s identity.
  • none - Use this when the client does not authenticate itself at the token endpoint, either because it uses only the Implicit Flow (and so does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication mechanism.
Request Body schema: application/x-www-form-urlencoded
grant_type
string

Grant type can be one of the followings: authorization_code, password, client_credentials, refresh_token. Determines the mechanism iWelcome uses to authorize the creation of the tokens.

client_id
string

Obtained during either manual client registration or via the Dynamic Client Registration API. It identifies the client and must match the value preregistered in iWelcome.

client_secret
string

Obtained during either manual client registration or via the Dynamic Client Registration API.

redirect_uri
string

Required if grant_type is authorization_code. Specifies the callback location where the authorization was sent. This value must match the redirect_uri used to generate the original authorization_code.

state
string

State to more correctly identify responses.

code
string

Required if grant_type is authorization_code. The value is what was returned from the authorization endpoint.

scope
string

Required if password is the grant_type. This is a list of scopes that the client wants to be included in the access token. For the refresh_token grant type, these scopes have to be a subset of the scopes used to generate the refresh token in the first place.

username
string

Required if the grant_type is password.

password
string

Required if the grant_type is password.

refresh_token
string

Required if grant_type is refresh_token. The value is a valid refresh token that was returned from this endpoint previously.

code_verifier
string

Required if grant_type is authorization_code and code_challenge was specified in the original/authorize request. This value is the code verifier for PKCE. iWelcome uses it to recompute the code_challenge and verify if it matches the original code_challenge in the authorization request.

client_assertion_type
string

This specifies the type of client assertion that’s passed. The value of the client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".

client_assertion
string

The value of the client token obtained.

Responses

Response samples

Content type
application/json
{
  • "property1": { },
  • "property2": { }
}

OAuth2 OpenId connect endSession endpoint

Allows clients to terminate end-user sessions.

query Parameters
id_token_hint
required
string

Previously issued ID Token passed to the logout endpoint as a hint about the end-user's current authenticated session with the Client. This is used as an indication of the identity of the end-user that the RP is requesting to be logged out by the OP. The OP need not be listed as an audience of the ID Token when it is used as an id_token_hint value.

post_logout_redirect_uri
string

OPTIONAL. URL to which the RP is requesting that the end-user's User Agent be redirected after a logout has been performed. The value MUST have been previously registered with the OP, either using the post_logout_redirect_uris Registration parameter or via another mechanism. If supplied, the OP SHOULD honor this request following the logout.

state
string

OPTIONAL. Opaque value used by the RP to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter. If included in the logout request, the OP passes this value back to the RP using the state query parameter when redirecting the User Agent back to the RP.

Responses

OAuth2 related proprietary endpoint to obtain info about tokens. This endpoint is deprecated in favour or Introspect endpoint Deprecated

Get OAuth2 access token information.

query Parameters
access_token
required
string

Access_token

Responses

Response samples

Content type
application/json
{
  • "property1": { },
  • "property2": { }
}

OAuth2 well known endoint

Returns OAuth 2.0 metadata related to your Custom Authorization Server. This information can be used by clients to programmatically configure their interactions with iWelcome.

Responses

Response samples

Content type
application/json
{
  • "property1": { },
  • "property2": { }
}

OAuth2 userinfo endoint

Get OAuth2 user info endpoint. Returns information about the authenticated user.

header Parameters
Authorization
required
string

You must include an access token (returned from the OAuth2 access_token endpoint) in the HTTP Authorization header

Responses

Response samples

Content type
application/json
{
  • "property1": { },
  • "property2": { }
}

OAuth2 revocation endoint

Enables a client to revoke a token. If you are revoking a refresh token, then both the refresh token and any other associated access tokens will also be revoked. To make requests to this endpoint, you must include the client authentication in the request which can vary depending on the authentication method that the application is configured with. iWelcome supports the following authentication methods:

  • client_secret_basic, client_secret_post: Use one of these methods when the client has a client secret. Public clients (such as single-page and mobile apps) that can't protect a client secret must use none authentication method.
  • private_key_jwt: This method uses a client-generated JWT signed with an asymmetric key to confirm the client’s identity.
  • none - Use this when the client does not authenticate itself at the token endpoint, either because it uses only the Implicit Flow (and so does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication mechanism.
Request Body schema: application/x-www-form-urlencoded
token
required
string

OAuth2 token to be revoked

token_type_hint
string
Enum: "access_token" "refresh_token"

A hint about the type of the submitted token

client_id
string

The client ID of the application

client_secret
string

Obtained during either manual client registration or via the Dynamic Client Registration API.

client_assertion_type
string

The value of the [OAuth.Assertions] client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

client_assertion
string

The authentication token

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

OAuth2 token introspection endoint

Returns meta information related to an access token, including whether this token is currently active. To make requests to this endpoint, you must include the client authentication in the request which can vary depending on the authentication method that the application is configured with. iWelcome supports the following authentication methods:

  • client_secret_basic, client_secret_post: Use one of these methods when the client has a client secret. Public clients (such as single-page and mobile apps) that can't protect a client secret must use none authentication method.
  • private_key_jwt: This method uses a client-generated JWT signed with an asymmetric key to confirm the client's identity.
  • none - Use this when the client does not authenticate itself at the token endpoint, either because it uses only the Implicit Flow (and so does not use the Token Endpoint) or because it is a Public Client with no Client Secret or other authentication mechanism.
Request Body schema: application/x-www-form-urlencoded
token
required
string

An access token or refresh token.

token_type_hint
string
Enum: "access_token" "refresh_token"

A hint about the type of the submitted token

client_id
string

The client ID of the application

client_secret
string

Obtained during either manual client registration or via the Dynamic Client Registration API.

client_assertion_type
string

The value of the [OAuth.Assertions] client_assertion_type parameter MUST be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

client_assertion
string

The authentication token

Responses

Response samples

Content type
application/json
{
  • "property1": { },
  • "property2": { }
}

OAuth2 device flow initiation (device code issuer) endpoint

Upon calling this API, it will generate a user code and a device code.

Request Body schema: application/x-www-form-urlencoded
client_id
required
string

The client ID of the application

scope
string

A space-delimited list of permissions that the application requires.

Responses

Response samples

Content type
application/json
{
  • "user_code": "string",
  • "device_code": "string",
  • "verification_url": "string",
  • "expires_in": 0,
  • "interval": 0
}

OAuth2 device flow verification endpoint

The purpose of this API is to verify the user_code in order to pair the device with your account.

header Parameters
Authorization
required
string

The oauth2 access token

Request Body schema: application/x-www-form-urlencoded
user_code
required
string

The OAuth2 device flow user_code to verify

decision
required
string
Enum: "allow" "deny"

OAuth2 decision

save_consent
string
Enum: "on" "off"

Used to decide whether to save the consent for later or not

Responses

Response samples

Content type
application/json
{ }