User-restricted endpoints
@@ -128,23 +130,23 @@ Example
- | response_type |
+ response_type |
The OAuth 2.0 response type. Currently the only acceptable value is "code". |
- | client_id |
+ client_id |
The Client ID of your application. |
- | scope |
+ scope |
A space-delimited list of scopes you would like to have permission to access on behalf of your user. |
- | state (optional) |
- An opaque value used to maintain state between the request and callback and to prevent tampering as described in the Oauth 2.0 specification (opens in a new tab). This is passed back to your application via the redirect_uri. |
+ state (optional) |
+ An opaque value used to maintain state between the request and callback and to prevent tampering as described in the Oauth 2.0 specification (opens in a new tab). This is passed back to your application via the redirect_uri. |
- | redirect_uri |
+ redirect_uri |
The URI that we use to send users back to your application after successful (or unsuccessful) authorisation.
For more details see our reference guide.
|
@@ -240,25 +242,25 @@ 2. Receive authorisation results
- | code |
+ code |
The authorisation code, if authorisation is successful.
This is a single-use token that expires 10 minutes after it's issued. |
- | state |
+ state |
The value of the state parameter you provided in the authorisation request, whether or not authorisation is successful. |
- | error |
- Always access_denied, if authorisation failed. |
+ error |
+ Always access_denied, if authorisation failed. |
- | error_description |
+ error_description |
Human readable description of the error, if authorisation failed, for example, “user denied the authorization”. |
- | error_code |
- Error code, if authorisation failed, for example, USER_DENIED_AUTHORIZATION
+ | error_code |
+ Error code, if authorisation failed, for example, USER_DENIED_AUTHORIZATION
The full list of error codes can change over time, so we recommend you do not cater for specific error codes. |
@@ -267,14 +269,12 @@ 2. Receive authorisation results
Here’s an example of a redirect we issue after a successful authorisation:
-GET
-https://www.example.com?code=TBC&state=123e4567-e89b-12d3-a456-426655440000
+GET https://www.example.com?code=TBC&state=123e4567-e89b-12d3-a456-426655440000
Here’s an example of a redirect we issue after an unsuccessful authorisation:
-GET
-https://www.example.com?error=access_denied
+GET https://www.example.com?error=access_denied
&error_description=user+denied+the+authorization
&error_code=USER_DENIED_AUTHORIZATION
&state=123e4567-e89b-12d3-a456-426655440000
@@ -285,10 +285,10 @@ 2. Receive authorisation results
3. Exchange authorisation code for access token
- When you get the authorisation code, your application must exchange this for an access_token within 10 minutes before it expires.
+
When you get the authorisation code, your application must exchange this for an access_token within 10 minutes before it expires.
- Do this via a POST to our token endpoint using grant_type of authorization_code.
+ Do this via a POST to our token endpoint using grant_type of authorization_code.
The response contains the access token used for calling the APIs and a refresh token used to obtain a new access token once the current one expires.
@@ -296,18 +296,19 @@ Example request
curl -X POST --data
-'client_secret=[YOUR-CLIENT-SECRET]&client_id=[YOUR-CLIENT-ID]&grant_type=authorization_code&redirect_uri=[YOUR-REDIRECT-URI]&code=[AUTHORIZATION-CODE]' \ https://test-api.service.hmrc.gov.uk/oauth/token
+'client_secret=[YOUR-CLIENT-SECRET]&client_id=[YOUR-CLIENT-ID]&grant_type=authorization_code&redirect_uri=[YOUR-REDIRECT-URI]&code=[AUTHORIZATION-CODE]' \
+https://test-api.service.hmrc.gov.uk/oauth/token
Example response
{
-"access_token": "QGbWG8KckncuwwD4uYXgWxF4HQvuPmrmUqKgkpQP",
-"token_type": "bearer",
-"expires_in": 14400,
-"refresh_token": "unJkSs5cvs8CS9E4DLvTkNhcRBq9BwUPm23cr3pF",
-"scope": "read:employment"
+ "access_token": "QGbWG8KckncuwwD4uYXgWxF4HQvuPmrmUqKgkpQP",
+ "token_type": "bearer",
+ "expires_in": 14400,
+ "refresh_token": "unJkSs5cvs8CS9E4DLvTkNhcRBq9BwUPm23cr3pF",
+ "scope": "read:employment"
}
@@ -387,13 +388,12 @@ Error codes
4. Call an API
- You can now call an API using the access_token we issued. Do this with an Authorization header containing this access_token as an OAuth 2.0 Bearer Token with the correct API scope.
+ You can now call an API using the access_token we issued. Do this with an Authorization header containing this access_token as an OAuth 2.0 Bearer Token with the correct API scope.
Example request
-curl -X GET \
-https://test-api.service.hmrc.gov.uk/oauth/token \
+curl -X GET https://test-api.service.hmrc.gov.uk/oauth/token \
-H ‘Accept: application/vnd.hmrc.1.0+json’ \
-H ‘Authorization: Bearer [ACCESS-TOKEN]’
@@ -403,31 +403,32 @@ Example request
5. Refreshing an access token
- A user's access_token expires after 4 hours.
+ A user's access_token expires after 4 hours.
- If the user's access_token has expired, when your application calls an API it receives a response with an HTTP status code of 401 (Unauthorized) and an error code of INVALID_CREDENTIALS.
+ If the user's access_token has expired, when your application calls an API it receives a response with an HTTP status code of 401 (Unauthorized) and an error code of INVALID_CREDENTIALS.
- To refresh the access_token, submit the expired token’s corresponding refresh_token to our token endpoint using grant_type of refresh_token.
+ To refresh the access_token, submit the expired token’s corresponding refresh_token to our token endpoint using grant_type of refresh_token.
- You can only use a refresh_token once. When you refresh an access_token, it invalidates the original access_token immediately if it has not already expired.
+ You can only use a refresh_token once. When you refresh an access_token, it invalidates the original access_token immediately if it has not already expired.
Therefore, be careful to avoid creating any race conditions when refreshing access tokens if your application supports concurrent API access.
Example request
-curl --data
-'client_secret=[YOUR-CLIENT-SECRET]&client_id=[YOUR-CLIENT-ID]&grant_type=refresh_token&refresh_token=[REFRESH-TOKEN]' \https://test-api.service.hmrc.gov.uk/oauth/token
+curl -X POST --data
+'client_secret=[YOUR-CLIENT-SECRET]&client_id=[YOUR-CLIENT-ID]&grant_type=refresh_token&refresh_token=[REFRESH-TOKEN]' \
+https://test-api.service.hmrc.gov.uk/oauth/token
Example response
{
-"access_token": "unJkSs5cvs8CS9E4DLvTkNhcRBq9BwUPm23cr3pF",
-"token_type": "bearer",
-"expires_in": 14400,
-"refresh_token": "jPtmQuLtKmLhGURk8CmR2sWPmffBhDhPyFEEF4ay"
+ "access_token": "unJkSs5cvs8CS9E4DLvTkNhcRBq9BwUPm23cr3pF",
+ "token_type": "bearer",
+ "expires_in": 14400,
+ "refresh_token": "jPtmQuLtKmLhGURk8CmR2sWPmffBhDhPyFEEF4ay"
}
Error codes
@@ -495,9 +496,9 @@ Error codes
Requesting a new token
- Unless revoked earlier by the user, or tampered with, the authorisation granted to your application expires after 18 months, and you can no longer refresh the user's access_token.
+ Unless revoked earlier by the user, or tampered with, the authorisation granted to your application expires after 18 months, and you can no longer refresh the user's access_token.
- If the user's refresh_token has expired, when your application calls our token endpoint, it receives a response with an HTTP status code of 400 (Bad Request) and an error code of invalid_request.
+ If the user's refresh_token has expired, when your application calls our token endpoint, it receives a response with an HTTP status code of 400 (Bad Request) and an error code of invalid_request.
When this happens, your application must send the user back through the full process for Getting an OAuth 2.0 access token.
@@ -535,15 +536,15 @@ authorization_code is returned to your application.
+
The Redirect URI determines how the authorization_code is returned to your application.
- Where your application is running on a remote web server, your Redirect URI returns the authorization_code to that server. You can then centrally manage your authorisation tokens.
+ Where your application is running on a remote web server, your Redirect URI returns the authorization_code to that server. You can then centrally manage your authorisation tokens.
In distributed applications, where your application is installed on a user's device and there's no centralised web server, you have the following options for a Redirect URI:
http://localhost:[PORT]
- The authorization_code is returned to a web server running on the client at the specified port.
+ The authorization_code is returned to a web server running on the client at the specified port.
This isn’t suitable in some situations, such as where a firewall stops your client from listening on a HTTP port.
@@ -551,9 +552,9 @@ http://localhost:[PORT]
urn:ietf:wg:oauth:2.0:oob
- The authorization_code is rendered in the title of a HTML page where you can parse the DOM to retrieve the code. You can then programmatically close the window before the user sees the rendered web page.
+ The authorization_code is rendered in the title of a HTML page where you can parse the DOM to retrieve the code. You can then programmatically close the window before the user sees the rendered web page.
- If your application can't parse the DOM or close the window, the HTML page renders the authorization_code along with a message asking the user to copy the code and paste it into your application, before closing the window.
+ If your application can't parse the DOM or close the window, the HTML page renders the authorization_code along with a message asking the user to copy the code and paste it into your application, before closing the window.
urn:ietf:wg:oauth:2.0:oob:auto
@@ -566,9 +567,9 @@ urn:ietf:wg:oauth:2.0:oob:auto
Managing your client secret
- Your client_secret is embedded in the source code of your application, and therefore isn't as secret as it would otherwise be.
+ Your client_secret is embedded in the source code of your application, and therefore isn't as secret as it would otherwise be.
- You should consider a rotation strategy for your client_secret, so that secrets are periodically rolled over to a new value. To support this the sandbox environment lets you simultaneously support multiple client_secret values for a single application.
+ You should consider a rotation strategy for your client_secret, so that secrets are periodically rolled over to a new value. To support this the sandbox environment lets you simultaneously support multiple client_secret values for a single application.
diff --git a/app/uk/gov/hmrc/apidocumentation/views/helpers/Helpers.scala b/app/uk/gov/hmrc/apidocumentation/views/helpers/Helpers.scala
index 58801e59..6daa6108 100644
--- a/app/uk/gov/hmrc/apidocumentation/views/helpers/Helpers.scala
+++ b/app/uk/gov/hmrc/apidocumentation/views/helpers/Helpers.scala
@@ -150,7 +150,7 @@ object Markdown {
.setDecorator(new ExtDecorator()
.addStyleClass("list list-bullet", "ul")
.addStyleClass("list list-number", "ol")
- .addStyleClass("code", "code")
+ .addStyleClass("code--slim", "code")
.addStyleClass("heading-large", "h1")
.addStyleClass("heading-medium", "h2")
.addStyleClass("heading-small", "h3")
diff --git a/app/uk/gov/hmrc/apidocumentation/views/include/main.scala.html b/app/uk/gov/hmrc/apidocumentation/views/include/main.scala.html
index 24868aa3..a192c652 100644
--- a/app/uk/gov/hmrc/apidocumentation/views/include/main.scala.html
+++ b/app/uk/gov/hmrc/apidocumentation/views/include/main.scala.html
@@ -157,7 +157,7 @@
