From c9f20ce55657b3d55fe49861fc57e2efb7972de8 Mon Sep 17 00:00:00 2001 From: Tony Heap Date: Fri, 23 Nov 2018 09:26:04 +0000 Subject: [PATCH] APIS-3710 - update auth docs, plus a load of cosmetic changes along the way --- app/assets/css/ad-hoc.scss | 11 +- .../views/authorisation.scala.html | 42 +-- .../views/authorisation2SV.scala.html | 36 +- ...orisationAppRestrictedEndpoints.scala.html | 44 +-- ...uthorisationOpenAccessEndpoints.scala.html | 47 +-- ...risationUserRestrictedEndpoints.scala.html | 320 ++++++++++-------- .../views/raml/resource_group.scala.html | 2 +- .../views/reference.scala.html | 142 ++++---- .../testUsersDataStatefulBehaviour.scala.html | 5 +- .../apidocumentation/views/testing.scala.html | 3 +- .../views/testingDataClearDown.scala.html | 3 +- .../views/tutorials.scala.html | 236 ++++++------- 12 files changed, 421 insertions(+), 470 deletions(-) diff --git a/app/assets/css/ad-hoc.scss b/app/assets/css/ad-hoc.scss index 79ab6aef..9aba1a5c 100644 --- a/app/assets/css/ad-hoc.scss +++ b/app/assets/css/ad-hoc.scss @@ -16,15 +16,6 @@ -// APIS-1076 - Temporary vertical alignment for Sandbox tables. -.sandbox-data { - td { - vertical-align: top - } -} - - - // APIS-1079 - Add margin to bottom of bullets. .bullets + p { margin-top: 1.2em; @@ -120,7 +111,7 @@ tbody { vertical-align: top; } td { - vertical-align: baseline; + vertical-align: top; } pre, code { diff --git a/app/uk/gov/hmrc/apidocumentation/views/authorisation.scala.html b/app/uk/gov/hmrc/apidocumentation/views/authorisation.scala.html index 1096c8fe..87ebd995 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/authorisation.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/authorisation.scala.html @@ -24,37 +24,17 @@ @apiMain(pageAttributes) { -

Authorisation

+

Authorisation

@@ -90,11 +70,11 @@

Introduction

Application-restricted - server_token + server_token User-restricted - OAuth 2.0 access_token + OAuth 2.0 access_token diff --git a/app/uk/gov/hmrc/apidocumentation/views/authorisation2SV.scala.html b/app/uk/gov/hmrc/apidocumentation/views/authorisation2SV.scala.html index 4ae8f034..5700e95b 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/authorisation2SV.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/authorisation2SV.scala.html @@ -27,34 +27,14 @@

Authorisation

diff --git a/app/uk/gov/hmrc/apidocumentation/views/authorisationAppRestrictedEndpoints.scala.html b/app/uk/gov/hmrc/apidocumentation/views/authorisationAppRestrictedEndpoints.scala.html index 54e47c3d..1c5ff078 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/authorisationAppRestrictedEndpoints.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/authorisationAppRestrictedEndpoints.scala.html @@ -24,37 +24,17 @@ @apiMain(pageAttributes) { -

Authorisation

+

Authorisation

@@ -68,15 +48,15 @@

Application-restricted endpoints

Example

-
+
 curl -H 'Authorization: Bearer [YOUR-SERVER-TOKEN]' \
 -H 'Accept: application/vnd.hmrc.1.0+json' \
-@{applicationConfig.productionApiBaseUrl}/hello/application'

+@{applicationConfig.sandboxApiBaseUrl}/hello/application

If you’ve already been issued a valid OAuth 2.0 access_token, you can substitute this with a server_token.

-

For a working example see the application-restricted endpoint tutorial.

+

For a working example, see the application-restricted endpoint tutorial.

diff --git a/app/uk/gov/hmrc/apidocumentation/views/authorisationOpenAccessEndpoints.scala.html b/app/uk/gov/hmrc/apidocumentation/views/authorisationOpenAccessEndpoints.scala.html index 1828c4fc..36f25505 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/authorisationOpenAccessEndpoints.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/authorisationOpenAccessEndpoints.scala.html @@ -24,38 +24,19 @@ @apiMain(pageAttributes) { -

Authorisation

+

Authorisation

- +
@@ -66,12 +47,12 @@

Open access endpoints

Example

-
-curl -H 'Content-Type: application/vnd.hmrc.v1+json' \
-@{applicationConfig.productionApiBaseUrl}/hello/world
+
+curl -H 'Accept: application/vnd.hmrc.1.0+json' \
+@{applicationConfig.sandboxApiBaseUrl}/hello/world
 

 
-        
For a working example see the open access endpoint tutorial.

+        
For a working example, see the open access endpoint tutorial.
diff --git a/app/uk/gov/hmrc/apidocumentation/views/authorisationUserRestrictedEndpoints.scala.html b/app/uk/gov/hmrc/apidocumentation/views/authorisationUserRestrictedEndpoints.scala.html index a5da0633..01e0dac9 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/authorisationUserRestrictedEndpoints.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/authorisationUserRestrictedEndpoints.scala.html @@ -27,33 +27,14 @@

Authorisation

@@ -64,18 +45,24 @@

User-restricted endpoints

These endpoints require specific authorisation from the end user. They generally give access to sensitive personal data.

-

We use the open standard OAuth 2.0 (opens in a new tab). This lets the end user grant authority to a third-party application to interact with HMRC on their behalf, without sharing their access credentials.

+

We use the open standard OAuth 2.0 (opens in a new tab). This lets the end user grant authority to your application to interact with HMRC on their behalf, without sharing their access credentials.

The end user authenticates directly with us using their Government Gateway account, and grants authority for specific scopes.

-

We then issue an OAuth 2.0 access token (opens in a new tab) that’s specific to the end user. The third-party application passes the access token in subsequent API requests to user-restricted endpoints.

+

We then issue an OAuth 2.0 access token (opens in a new tab) that’s specific to the end user. Your application passes the access token in subsequent API requests to user-restricted endpoints.

There are separate Government Gateway accounts for individuals, agents and organisations. For individuals and organisations, the access token only gives access to the end user’s own data. For agents the access token gives access to their clients’ data.

-

Authorisation rules for specific API resources are given in the API documentation.

+

Authorisation rules for specific API endpoints are given in the API documentation.

The access token expires every 4 hours and must be refreshed using a single-use refresh token. After 18 months you can no longer refresh the access token and the end user must grant authority again.

+
+

+ For a working example, see the user-restricted endpoint tutorial. +

+
+

Getting an OAuth 2.0 access token

@@ -96,7 +83,7 @@

Getting an OAuth 2.0 access token

1. Request authorisation

    -
  1. Send your user to the authorisation endpoint.
    2. +
  2. Send your user to the authorisation endpoint.
  3. We display a start page that explains the authorisation process.
  4. We prompt the user to sign in using their Government Gateway account.
  5. The user is taken through 2-Step Verification (2SV).
    6. @@ -112,14 +99,23 @@

    1. Request authorisation

    alt="API user auth journey" width="50%"/> -
    Example
    +
    Syntax
    - 
    +            
     GET  @{applicationConfig.sandboxApiBaseUrl}/oauth/authorize?response_type=code
 &client_id=[YOUR-CLIENT-ID]
 &scope=[REQUESTED-SCOPE]
 &state=[STATE]
 &redirect_uri=[YOUR-REDIRECT-URI]
    
+                    
+            
    Example
    
+
+            
    +GET  @{applicationConfig.sandboxApiBaseUrl}/oauth/authorize?response_type=code
+&client_id=Hf8sfkiUkYp9I3_R10qSnZ2ZUvoa
+&scope=scope_1+scope_2+scope_3
+&state=30de877c-ee2f-15db-8314-0800200c9a66
+&redirect_uri=https://www.example.com/auth-redirect
    
 
             
@@ -131,23 +127,23 @@ 
    Example
    
-                    
-                    
+                    
+                    
-                    
+                    
-                    
-                    
+                    
+                    
-                    
-                    
+                    
+                    
-                    
+                    
@@ -155,67 +151,85 @@ 
    Example
    
                 
                 
                 
                 
    response_typeThe OAuth 2.0 response type. Currently the only acceptable value is "code".response_typeThe OAuth 2.0 response type. Currently the only acceptable value is code.
                 
    
                 
    client_idclient_id
                     The Client ID of your application.
                 
    
                 
    scopeA space-delimited list of scopes you  would like to have permission to access on behalf of your user.scopeA space-delimited list of scopes you  would like to have permission to access on behalf of your user. Must be percent-encoded, so spaces must be represented as either %20 or +.
                 
    
                 
    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_uriredirect_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.
                         		
                 
    
             
    
 
-            
    Error codes
    
+            
    Error scenarios
    
+
+            
    If there are any issues with your call to our authorisation endpoint, we return an HTTP error status to your user’s browser.
    
+
+            
    Any errors not listed have probably not come from us. One possible cause is a network access issue.
    
+
+            
    
+                
    The error codes listed are fixed, but the associated error messages can change without notice.
    
+            
    
 
             
-                
+                
-                    
+                    
+                    
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
    
                 
                 
    
                     Error scenario
                     HTTP statusCodeError codeError message
                 
    
                     
                 
                     
    
                         Client ID is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestclient_id is required
                     
    
                     
    
                         Client ID is invalid400 (Bad Request)invalid_request400 (Bad Request)invalid_requestclient_id is invalid
                     
    
                     
    
                         Redirect URI is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestredirect_uri is required
                     
    
                     
    
                         Redirect URI is invalid400 (Bad Request)invalid_request400 (Bad Request)invalid_requestredirect_uri is invalid
                     
    
                     
    
                         Response Type is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestresponse_type is required
                     
    
                     
    
                         Response Type is invalid400 (Bad Request)unsupported_response_type400 (Bad Request)unsupported_response_typeresponse_type must be 'code'
                     
    
                     
    
                         Scope is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestscope is required
                     
    
                     
    
                         Scope is invalid400 (Bad Request)invalid_scope400 (Bad Request)invalid_scopescope is invalid
                     
    
                     
    
                         Unexpected error occurred500 (Internal Server Error)server_error500 (Internal Server Error)server_errorVarious
                     
    
                     
             
    
 
-            
    Browser support
    
+            
    Browser support
    
 
             
    For details of which browsers we support for the authorisation journey see
                 
@@ -243,25 +257,25 @@ 
    2. Receive authorisation results
    
                 
                 
                     
-                        code
-                        The authorisation code, if authorisation is successful.

    
+                        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.
                     
                 
@@ -269,12 +283,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
    
 
             
    Here’s an example of a redirect we issue after an unsuccessful authorisation:
    
 
-            
    +            
     GET https://www.example.com?error=access_denied
 &error_description=user+denied+the+authorization
 &error_code=USER_DENIED_AUTHORIZATION
@@ -286,16 +300,16 @@ 
    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.
    
 
             
    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]' \
 @{applicationConfig.sandboxApiBaseUrl}/oauth/token
@@ -303,7 +317,7 @@ 
    Example request
    
 
             
    Example response
    
 
-            
    +            
     {
   "access_token": "QGbWG8KckncuwwD4uYXgWxF4HQvuPmrmUqKgkpQP",
   "token_type": "bearer",
@@ -313,72 +327,92 @@ 
    Example response
    
 }
 
    
 
-            
    Error codes
    
+            
    Error scenarios
    
+
+            
    If there are any issues with your call to our token endpoint, we return an HTTP error status.
    
+
+            
    Any errors not listed have probably not come from us. One possible cause is a network access issue, for example your network might allow GET requests but not POST requests.
    
+
+            
    
+                
    The error codes listed are fixed, but the associated error messages can change without notice.
    
+            
    
 
             
-                
+                
-                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
-                        
-                        
+                        
+                        
+                        
    
                 
                     
    
                         Error scenario
                         HTTP statusCodeError codeError message
                     
    
                     
                 
                     
    
                         Client ID is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestclient_id is required
                     
    
                     
    
                         Client ID is invalid401 (Unauthorized)invalid_client401 (Unauthorized)invalid_clientinvalid client id or secret
                     
    
                     
    
                         Client Secret is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestclient_secret is required
                     
    
                     
    
                         Client Secret is invalid401 (Unauthorized)invalid_client401 (Unauthorized)invalid_clientinvalid client id or secret
                     
    
                     
    
                         Grant Type is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestgrant_type is required
                     
    
                     
    
                         Grant Type is invalid400 (Bad Request)invalid_request400 (Bad Request)invalid_requestunsupported grant_type
                     
    
                     
    
                         Redirect URI is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestredirect_uri is required
                     
    
                     
    
                         Redirect URI is invalid400 (Bad Request)invalid_request400 (Bad Request)invalid_requestredirect_uri is invalid
                     
    
                     
    
                         Code is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_requestcode is required for given grant_type
                     
    
                     
    
                         Code is invalid400 (Bad Request)invalid_request400 (Bad Request)invalid_requestcode is invalid
                     
    
                     
    
                         Unexpected error occurred500 (Internal Server Error)server_error500 (Internal Server Error)server_errorVarious
                     
    
                     
             
    
@@ -389,11 +423,11 @@ 
    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 @{applicationConfig.sandboxApiBaseUrl}/oauth/token \
 -H ‘Accept: application/vnd.hmrc.1.0+json’ \
 -H ‘Authorization: Bearer [ACCESS-TOKEN]’
    
@@ -404,19 +438,19 @@ 
    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 -X POST --data \
 'client_secret=[YOUR-CLIENT-SECRET]&client_id=[YOUR-CLIENT-ID]&grant_type=refresh_token&refresh_token=[REFRESH-TOKEN]' \
 @{applicationConfig.sandboxApiBaseUrl}/oauth/token
@@ -424,69 +458,73 @@ 
    Example request
    
 
             
    Example response
    
 
-            
    +            
     {
   "access_token": "unJkSs5cvs8CS9E4DLvTkNhcRBq9BwUPm23cr3pF",
   "token_type": "bearer",
   "expires_in": 14400,
   "refresh_token": "jPtmQuLtKmLhGURk8CmR2sWPmffBhDhPyFEEF4ay"
 }
    
-            
    Error codes
    
+            
    Error scenarios
    
+
+            
    If there are any issues with your call to our token endpoint, we return an HTTP error status.
    
+
+            
    Any errors not listed have probably not come from us. One possible cause is a network access issue.
    
 
             
-                
+                
-                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
-                        
-                        
+                        
+                        
    
                 
                     
    
                         Error scenario
                         HTTP statusCodeError code
                     
    
                     
                 
                     
    
                         Client ID is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_request
                     
    
                     
    
                         Client ID is invalid401 (Unauthorized)invalid_client401 (Unauthorized)invalid_client
                     
    
                     
    
                         Client Secret is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_request
                     
    
                     
    
                         Client Secret is invalid401 (Unauthorized)invalid_client401 (Unauthorized)invalid_client
                     
    
                     
    
                         Grant Type is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_request
                     
    
                     
    
                         Grant Type is invalid400 (Bad Request)invalid_request400 (Bad Request)invalid_request
                     
    
                     
    
                         Refresh Token is missing400 (Bad Request)invalid_request400 (Bad Request)invalid_request
                     
    
                     
    
                         Refresh Token is invalid400 (Bad Request)invalid_grant400 (Bad Request)invalid_grant
                     
    
                     
    
                         Unexpected error occurred500 (Internal Server Error)server_error500 (Internal Server Error)server_error
                     
    
                     
             
    
@@ -497,15 +535,15 @@ 
    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.
    
 
         
    
             
    
-                For a working example see the user-restricted endpoint tutorial.
+                For a working example, see the user-restricted endpoint tutorial.
             
    
         
    
 
@@ -537,15 +575,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.
    
 
@@ -553,9 +591,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
    
 
@@ -568,9 +606,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/raml/resource_group.scala.html b/app/uk/gov/hmrc/apidocumentation/views/raml/resource_group.scala.html index cb21ab1f..2e46d683 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/raml/resource_group.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/raml/resource_group.scala.html @@ -48,7 +48,7 @@

@titleSection resources

@if(index == 0) {
@defining(res.resourcePath.split("/").toSeq) { case head :+ tail => - @{head.mkString("/")}/@tail + @{head.mkString("/")}/@tail }
} diff --git a/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html b/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html index ec410a0f..045100ce 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html @@ -57,9 +57,9 @@

API access

The base URL for sandbox APIs is:

- 
@applicationConfig.sandboxApiBaseUrl
+ 
@applicationConfig.sandboxApiBaseUrl

The base URL for production APIs is:

- 
@applicationConfig.productionApiBaseUrl
+ 
@applicationConfig.productionApiBaseUrl
@@ -71,11 +71,11 @@

Network access

access in your proxy, not your firewall.

Configure your proxy to allow full access to the following domains, including HTTP GET, POST, PUT and DELETE.

For testing in sandbox:

- 
+        
 @applicationConfig.sandboxApiHost
 @applicationConfig.sandboxWwwHost

         
For production use:

-        
+        
 @applicationConfig.productionApiHost
 @applicationConfig.productionWwwHost
@@ -102,23 +102,23 @@

Common data types

- date - "2015-09-08" + date + 2015-09-08 Dates will be represented in the format YYYY-MM-DD. - timestamp - "2015-09-08T01:55:28+00:00" + timestamp + 2015-09-08T01:55:28+00:00 Timestamps will be represented in the format YYYY-MM-DDThh:mm:ss±hh:mm. - money - 123.45 + money + 123.45 Unless expressly documented, money will be represented with two decimal places and GBP currency. - NINO - "QQ123456A" + NINO + QQ123456A A National Insurance number is made up of 2 letters, 6 numbers and a letter (A, B, C, or D). @@ -152,27 +152,27 @@

Common API Errors

- code - string + code + string A machine-readable error code. This is unique for each error scenario. - message - string + message + string A human-readable explanation for the error.

There might be other error-specific information (such as a list of fields that are in error). For example:

- 
{
+            
{
   "code" : "ACCOUNT_SUSPENDEDSA-100201",
   "message" : "Account is temporarily suspended",
   "reactivationTimestamp" : 1431448640718
 }
 

             
Multiple errors can also be returned in a single field called errors. For example:

-            
+            
 {
   "code": "BAD_REQUEST",
   "message": "Bad request",
@@ -191,7 +191,7 @@ 
Common API Errors

 }
 

             
Here is an example error response in XML format

-            
+            
 <error>
   <code>ACCOUNT_SUSPENDEDSA-100201</code>
   <message>Account is temporarily suspended</message>
@@ -212,19 +212,19 @@ 
401 (Unauthorized)

                 
                 
                     No OAuth token supplied for user-restricted or application-restricted resource
-                    MISSING_CREDENTIALS
+                    MISSING_CREDENTIALS
                 
                 
                     Invalid OAuth token supplied for user-restricted or application-restricted resource (including expired token)
-                    INVALID_CREDENTIALS
+                    INVALID_CREDENTIALS
                 
                 
                     Supplied OAuth token not authorised to access data for given tax identifier(s)
-                    UNAUTHORIZED
+                    UNAUTHORIZED
                 
                 
                     User-restricted API is being accessed with a server token
-                    INCORRECT_ACCESS_TOKEN_TYPE
+                    INCORRECT_ACCESS_TOKEN_TYPE
                 
                 
             
@@ -241,19 +241,19 @@ 
403 (Forbidden)

                 
                 
                     Request done with HTTP
-                    HTTPS_REQUIRED
+                    HTTPS_REQUIRED
                 
                 
                     Production tokens used for Beta API
-                    API_NOT_IN_PRODUCTION
+                    API_NOT_IN_PRODUCTION
                 
                 
                     The OAuth token's application is not subscribed to the API
-                    RESOURCE_FORBIDDEN
+                    RESOURCE_FORBIDDEN
                 
                 
                     The scope of the OAuth token is not sufficient to access the API
-                    INVALID_SCOPE
+                    INVALID_SCOPE
                 
                 
             
@@ -271,11 +271,11 @@ 
404 (Not Found)

                 
                 
                     No endpoint could be found in the API for the request path
-                    MATCHING_RESOURCE_NOT_FOUND
+                    MATCHING_RESOURCE_NOT_FOUND
                 
                 
                     No API could be found for the context
-                    NOT_FOUND
+                    NOT_FOUND
                 
                 
             
@@ -293,7 +293,7 @@ 
405 (Method Not Allowed)

                 
                 
                     Request method is not GET, PUT, POST, DELETE or OPTIONS
-                    METHOD_NOT_ALLOWED
+                    METHOD_NOT_ALLOWED
                 
                 
             
@@ -310,7 +310,7 @@ 
406 (Not Acceptable)

                 
                 
                     Missing or invalid Accept header
-                    ACCEPT_HEADER_INVALID
+                    ACCEPT_HEADER_INVALID
                 
                 
             
@@ -327,7 +327,7 @@ 
429 (Too Many Requests)

                 
                 
                     The application has reached its maximum rate limit
-                    MESSAGE_THROTTLED_OUT
+                    MESSAGE_THROTTLED_OUT
                 
                 
             
@@ -344,7 +344,7 @@ 
500 (Internal Server Error)

                 
                 
                     Internal server error
-                    INTERNAL_SERVER_ERROR
+                    INTERNAL_SERVER_ERROR
                 
                 
             
@@ -361,7 +361,7 @@ 
501 (Not Implemented)

                 
                 
                     API not implemented/deployed
-                    NOT_IMPLEMENTED
+                    NOT_IMPLEMENTED
                 
                 
             
@@ -378,11 +378,11 @@ 
503 (Service Unavailable)

                 
                 
                     Service unavailable
-                    SERVER_ERROR
+                    SERVER_ERROR
                 
                 
                     Scheduled maintenance
-                    SCHEDULED_MAINTENANCE
+                    SCHEDULED_MAINTENANCE
                 
                 
             
@@ -399,7 +399,7 @@ 
504 (Gateway Timeout)

                 
                 
                     Request timed out
-                    GATEWAY_TIMEOUT
+                    GATEWAY_TIMEOUT
                 
                 
             
@@ -453,11 +453,11 @@ 
Versioning

 
         
You can request a specific version of an API by using an Accept header with a media type of:

 
-        
application/vnd.hmrc.[version]+[content-type]

+        
application/vnd.hmrc.[version]+[content-type]

 
         
For example:

 
-        
application/vnd.hmrc.1.0+json

+        
application/vnd.hmrc.1.0+json

 
         
Media types are specific to each resource, which lets them change separately from one another.

 
@@ -522,21 +522,21 @@ 
Header Contents

             
             
                 
-                    Gov-Client-Public-IP
+                    Gov-Client-Public-IP
                     
                         
The public IP address of the originating client machine.

                         
For example, 198.51.100.0

                     
                 
                 
-                    Gov-Client-Public-Port
+                    Gov-Client-Public-Port
                     
                         
The port component of the Gov-Client-Public-IP.

                         
For example, 12345

                     
                 
                 
-                    Gov-Client-Device-ID
+                    Gov-Client-Device-ID
                     
                         

                             A consistent ID representing the originating client machine. This depends on the context.
@@ -547,7 +547,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-User-ID
+                    Gov-Client-User-ID
                     
                         

                             The identifier that the customer used to login to the client machine, and/or the software vendor’s software or website. Provide multiple identifiers as a comma-delimited list. Use N/A if no identifiers are available.
@@ -561,21 +561,21 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Timezone
+                    Gov-Client-Timezone
                     
                         
Timezone of the clock on the client machine.

                         
For example, GMT+3

                     
                 
                 
-                    Gov-Client-Local-IP
+                    Gov-Client-Local-IP
                     
                         
Internal private IP address used by the client machine.

                         
For example, 10.1.2.3

                     
                 
                 
-                    Gov-Client-Screen-Resolution
+                    Gov-Client-Screen-Resolution
                     
                         
Methods A to E only.

                         
Screen resolution of the client machine in pixels.

@@ -583,7 +583,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Window-Size
+                    Gov-Client-Window-Size
                     
                         
Methods A to E only.

                         
Size of the application or browser window on the client machine in pixels.

@@ -591,7 +591,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Colour-Depth
+                    Gov-Client-Colour-Depth
                     
                         
Methods A to E only.

                         
Colour depth of the client machine in bits per pixel.

@@ -599,7 +599,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-User-Agent
+                    Gov-Client-User-Agent
                     
                         
For methods A to D and F: "<OS Family>/<OS Version> (<Manufacturer> <Model>)"

                         
For example, Android/6.0.1 (Samsung Galaxy S4)

@@ -608,7 +608,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Browser-Plugins
+                    Gov-Client-Browser-Plugins
                     
                         
Method E only.

                         
List of installed browser plugins.

@@ -619,7 +619,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Browser-JS-User-Agent
+                    Gov-Client-Browser-JS-User-Agent
                     
                         
Method E only.

                           
User Agent value as reported by Javascript.

@@ -633,7 +633,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Browser-Do-Not-Track
+                    Gov-Client-Browser-Do-Not-Track
                     
                         
Method E only.

                         
Whether the browser has set the Do Not Track flag or not, if the client machine is using a web browser.

@@ -644,7 +644,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Client-Multi-Factor
+                    Gov-Client-Multi-Factor
                     
                         
Method E only.

                         

@@ -671,7 +671,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Vendor-Version
+                    Gov-Vendor-Version
                     
                         

                             The vendor’s software version.

@@ -693,7 +693,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Vendor-Instance-ID
+                    Gov-Vendor-Instance-ID
                     
                         

                             An identifier unique to a specific installation of the vendor’s software, either on a client
@@ -713,7 +713,7 @@ 
Header Contents

                     
                 
                 
-                    Gov-Vendor-Public-IP
+                    Gov-Vendor-Public-IP
                     
                         
The public IP address that the customer’s machine used to send requests to the software vendor.

                         

@@ -729,7 +729,7 @@ 
Header Contents

                     
                 
                 
-                    Forwarded
+                    Forwarded
                     
                         
Methods C to E.

                         
The Forwarded header is created and appended to by any intermediary server that handles the
@@ -781,54 +781,52 @@ 
Examples

             
             
             
-                https://www.example.com/auth-redirect
+                https://www.example.com/auth-redirect
                 Valid - when creating your application, you can use the full redirect URI or a partial URI, for example:
                     

-                    
https://www.example.com/auth-redirect
+                    
https://www.example.com/auth-redirect
                     

-                    
https://www.example.com
+                    
https://www.example.com
                     

                     
When calling our authorisation endpoint, your redirect URI must be percent-encoded, for example:
                     

-                    
-https%3A%2F%2Fwww.example.com%2Fauth-
-redirect

+                    
https%3A%2F%2Fwww.example.com%2Fauth-redirect
                 
             
             
-                https://www.example.com:8080/auth-redirect
+                https://www.example.com:8080/auth-redirect
                 Valid - includes a port number
             
             
-                http://www.example.com:8080/auth-redirect
+                http://www.example.com:8080/auth-redirect
                 Invalid - uses HTTP, not HTTPS (HTTP is OK for installed applications - see example below)
             
             
-                /auth-redirect
+                /auth-redirect
                 Invalid - is a relative URI, not an absolute URI
             
             
-                https://203.0.113.11/auth-redirect
+                https://203.0.113.11/auth-redirect
                 Invalid - uses an IP address, not a DNS name
             
             
-                https://www.example.com:8080/auth-redirect?some_parameter=some_value
+                https://www.example.com:8080/auth-redirect?some_parameter=some_value
                 Valid - includes a query component
             
             
-                https://www.example.com:8080/auth-redirect#some_fragment
+                https://www.example.com:8080/auth-redirect#some_fragment
                 Invalid - includes a fragment component
             
             
-                http://localhost:8080
+                http://localhost:8080
                 Valid - as explained in OAuth 2.0 for installed applications
             
             
-                urn:ietf:wg:oauth:2.0:oob
+                urn:ietf:wg:oauth:2.0:oob
                 Valid - as explained in OAuth 2.0 for installed applications
             
             
-                urn:ietf:wg:oauth:2.0:oob:auto
+                urn:ietf:wg:oauth:2.0:oob:auto
                 Valid - as explained in OAuth 2.0 for installed applications
             
             
diff --git a/app/uk/gov/hmrc/apidocumentation/views/testUsersDataStatefulBehaviour.scala.html b/app/uk/gov/hmrc/apidocumentation/views/testUsersDataStatefulBehaviour.scala.html
index c272d02a..971d266c 100644
--- a/app/uk/gov/hmrc/apidocumentation/views/testUsersDataStatefulBehaviour.scala.html
+++ b/app/uk/gov/hmrc/apidocumentation/views/testUsersDataStatefulBehaviour.scala.html
@@ -24,9 +24,10 @@
 
 @apiMain(pageAttributes) {
 
-        
Testing in the sandbox

+    
Testing in the sandbox

 
-