Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wiremock.io/llms.txt

Use this file to discover all available pages before exploring further.

Enterprise customers may wish to interact with the WireMock Cloud API from their own clients using OAuth 2.0. WireMock Cloud supports the OAuth 2.0 Device Authorization Flow for these customers.

​
Requirements

You will need to have requested the creation of a new OAuth Client by WireMock Cloud. You will need to tell us:
  • The maximum time you allow between interactions before the user has to reauthenticate
  • The maximum total time you allow between authentications, eve if the user is regularly interacting

​
Inputs

  • {client_id}: The OAuth client (in Auth0, the Application id) provided by WireMock Cloud

​
Initiate the Client

request
GET https://login.wiremock.cloud/.well-known/openid-configuration
Accept: application/json
returns:

​
discover_urls

{
  "token_endpoint": "{fully_qualified_url}",
  "device_authorization_endpoint": "{fully_qualified_url}",
  "revocation_endpoint": "{fully_qualified_url}"
}

​
Initiate the Device Authorization Flow

request
POST {discover_urls.device_authorization_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&audience=https%3A%2F%2Fapi.wiremock.cloud&scope=openid+email+offline_access
returns:

​
device_authorization

{
  "device_code": "{random_value}",
  "user_code": "{legible_random_value}",
  "verification_uri": "{fully_qualified_url}",
  "expires_in": 900,
  "interval": 5,
  "verification_uri_complete": "{fully_qualified_url}"
}
expires_in and interval are values in seconds.

​
Pass control to the user to authenticate

Something like this should be rendered: 
Attempting to automatically open the authentication page in your default browser.

Code: {device_authorization.user_code}

If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

{device_authorization.verification_uri_complete}

Waiting for login...
if possible, {device_authorization.verification_uri_complete} should be opened automatically in the user’s browser.

​
Poll for successful authentication

Every {device_authorization.interval} seconds until {device_authorization.expires_in} seconds have passed you poll as so:
request
POST {discover_urls.token_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&device_code={device_authorization.device_code}&grant_type=urn:ietf:params:oauth:grant-type:device_code
You should be returned one of these two responses:
response
HTTP/2 403 Forbidden
Content-Type: application/json

{
  "error": "authorization_pending",
  "error_description": "User has yet to authorize device code."
}
which means “poll again in {device_authorization.interval} unless {device_authorization.expires_in} has passed” or

​
token_response

response
HTTP/2 200 OK
Content-Type: application/json

{
  "access_token": "{access_token}",
  "token_type": "{token_type}",
  "expires_in": 300,
  "refresh_token": "{refresh_token}",
  "id_token": {id_token}
}
You can then interact with the API using this request header: Authorization: {token_response.token_type} {token_response.access_token}

​
Refresh Tokens

WireMock access tokens are JWTs, and cannot be revoked. Consequently they are short-lived (sub 10 minutes). In order to avoid having to authenticate regularly, the client may exchange a refresh token (which can be revoked) for a new access token. A refresh token, once used, becomes invalid - a new one is returned along with the new access token. Any attempt to use an invalid refresh token will also invalidate the current valid refresh token, forcing a reauthentication. Refresh tokens can be explicitly revoked on logout.

​
Exchanging a refresh token for a new access token

request
POST {discover_urls.token_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&refresh_token={token_response.refresh_token}&grant_type=refresh_token
returns
token_response
{
  "access_token": "{access_token}",
  "token_type": "{token_type}",
  "expires_in": 300,
  "refresh_token": "{refresh_token}"
}

​
Invalidating a refresh token

request
POST {discover_urls.revocation_endpoint}
Content-Type: application/x-www-form-urlencoded

client_id={inputs.client_id}&token={token_response.refresh_token}