Custom registration v2

This endpoint requires the client to provide the client authentication in the form of a PrivateKeyJWT (urn:ietf:params:oauth:client-assertion-type:jwt-bearer) assertion. or more information, see authentication methods.

This API has specific demands for the PrivateKeyJWT authentication:

The JWT must be signed with algorithm ES256.
Its key identifier must be present as kid in the header of the JWT.
The signature is verified. Configure the public key or the JWKS endpoint in the client configuration.

Init step

The init step is only used for the TWO_STEP flow. The ONE_STEP flow uses the complete step.

Endpoint: POST /oauth/v2/custom-registration/{idp}/init

Parameter	Description
`idp`	Identity provider identifier

JSON body parameters:

Param	Required	Description
`client_assertion_type`	yes	The type of the client assertion that is part of the request. The only supported value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
`client_assertion`	yes	Client assertion in the form of a JWT signed by the client's private key
`data`	no	Raw registration request data that is provided to the extension engine

Example request

POST /oauth/v2/custom-registration/example-custom-registration-idp/init HTTP/1.1
Host: onewelcome.example.com
Content-Type: application/json

{
   "client_assertion_type" : "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
   "client_assertion" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
     eyJpc3Mi[...omitted for brevity...].
     cC4hiUPo[...omitted for brevity...]",
  "data" : "{\"custom_json_key\":\"custom json data\"}" // optional
 }

Example success response

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "transaction_id": "123123",   //something unique, should be passed with complete step
   "data": "12349876",           // e.g. a challenge code.
   "status": 2000
}

In the event of an error in the access service, one of the server error codes is returned.

It is up to the scripts executed by the extension engine to determine whether the request was successful when everything looks fine for the access service. For all these scenarios, a 200 OK JSON response is returned to the Mobile SDK and contains the following parameters:

Param	Description
`transaction_id`	Generated in the Init step. For TWO_STEP, this transaction identifier ensures that the same transaction is used.
`data`	Raw response coming from the script engine.
`status`	Status indicating whether the request was successful. See status codes.

Complete step

Endpoint: POST /oauth/v2/custom-registration/{idp}/complete

Parameter	Description
`idp`	Identity provider identifier

JSON body parameters

Param	Required	Description
`client_assertion_type`	yes	The type of the client assertion that is part of the request, currently the only supported value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
`client_assertion`	yes	Client assertion in the form of a JWT signed by the client's private key
`transaction_id`	yes (`TWO_STEP`) otherwise optional	Generated in the Init step. For `TWO_STEP`, ensures same transaction
`data`	no	Raw registration request data that is provided to the extension engine
`scope`	no	An array of scopes. If none are specified the default scopes are granted.
`profile_id`	yes (mobile client) otherwise optional	The profile ID of the user on the Mobile SDK, static clients can omit this. Profile ID must be 6 characters long.
`hook_context_custom_params`	no	A map of custom web-hook context-parameters used in web hooks
`grant_type`	no	Grant type that the access token is bound with. If not specified, the default grant type is used. Available values: `urn:onewelcome:oauth2:grant_type:stateless_authentication`

Example request

POST /oauth/v2/custom-registration/example-custom-registration-idp/complete HTTP/1.1
Host: onewelcome.example.com
Content-Type: application/json

{
   "client_assertion_type" : "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
   "client_assertion" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
     eyJpc3Mi[...omitted for brevity...].
     cC4hiUPo[...omitted for brevity...]",
  "transaction_id": "123123",
  "data": "{\"custom_json_key\":\"custom_ json data\"}",      //optional, e.g. challenge code response
  "scope": ["read", "write"],
  "hook_context_custom_params": {      //optional
     "on_behalf_of" : ["user"]
  }
}

Example successful response

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "status": 2000,
    "oauth_token": {
        "token_type": "bearer",
        "access_token": "8A5AB83A3C6B7AAC41471C1205167A35E0F9281ED277EE2FDE6E8DE30972936D",
        "refresh_token": "8CAE26B2B8E8EC18B4D432886448C7F99B558063C517BA41F30966B37C104983",
        "id_token": "eyJraWQiOiI1Nzk1[...omitted for brevity...]r9KM8c5y-Utpw",
        "expires_in": 3600
    },
    "data": "{\"custom_json_key\":\"custom json data\"}", // optional
}

Server error codes

In the event of an error in the access service, one of the following error codes is returned:

Status code	Error code	Description
400	invalid_request	Missing required parameter or the request is not correctly formatted.
400	invalid_request	Client authentication missing or not supported
400	invalid_client	Client authentication failed (such as unknown client, no client authentication included, or unsupported authentication method).
404	invalid_idp_identifier	The specified IDP does not exist.
403	idp_disabled	The specified IdP is disabled.
400	invalid_client	Not a valid client.
400	invalid_transaction	The transaction is invalid or has expired
400	invalid_scope	The requested scope is invalid, unknown or malformed.

It is up to the scripts execution in the extension engine to determine whether the request was successful when everything looks fine for the access service. For all these scenarios, a 200 OK JSON response is returned to the Mobile SDK and contains the following parameters:

Param	Description
`access_token`	Access token generated after successful completion of step
`refresh_token`	Refresh token generated after successful completion of step and client has them enabled
`expires_in`	Time until expiration in seconds
`token_type`	Token type
`id_token`	ID token with user data if the requested scope contains `openid`
`data`	Raw response coming from the script engine
`status`	Status indicating whether the request was successful. See status codes.

Extension engine status codes

Param	Value
`VALID_STATUS_MIN`	2000
`VALID_STATUS_MAX`	2999
`RETRY_STATUS_MIN`	4000
`RETRY_STATUS_MAX`	4999
`UNRECOVERABLE_STATUS_MIN`	5000
`UNRECOVERABLE_STATUS_MAX`	5999

Custom registration v2

Init step

JSON body parameters:

Example request

Example success response

Complete step

JSON body parameters

Example request

Example successful response

Server error codes

Extension engine status codes

On this page

Suggest A Change