### Example HTTP Request with Bearer Authentication Source: https://developer.company-information.service.gov.uk/authentication Illustrates the raw structure of an HTTP GET request including the Host header and the Authorization header for bearer token authentication. This provides a clear view of the HTTP protocol details for API interaction. ```http GET /company/00000006 HTTP/1.1 Host: api.company-information.service.gov.uk Authorization: Bearer my_access_token ``` -------------------------------- ### Example HTTP Bearer Authentication with cURL Source: https://developer.company-information.service.gov.uk/authentication Demonstrates how to set the Authorization HTTP request header using cURL for bearer token authentication when making a GET request to the Companies House API. This follows the specification defined by RFC2617. ```bash curl -XGET -H "Authorization: Bearer my_access_token" https://api.company-information.service.gov.uk/company/00000006 ``` -------------------------------- ### Raw HTTP Basic Authentication Request Example Source: https://developer.company-information.service.gov.uk/authentication Illustrates the raw HTTP request structure for sending an API key via HTTP Basic Authentication to the Companies House API. This shows the 'Authorization' header with the Base64 encoded API key. ```APIDOC GET /company/00000006 HTTP/1.1 Host: api.company-information.service.gov.uk Authorization: Basic bXlfYXBpX2tleTo= ``` -------------------------------- ### Perform a GET Request in REST API Source: https://developer.company-information.service.gov.uk/overview Demonstrates how to use the HTTP GET method to retrieve a specific resource from a RESTful API endpoint. This method is typically used for data retrieval without modifying the server state, leveraging the resource's unique URI. ```HTTP GET https://api.example.domain/customer/12345 HTTP/1.1 ``` -------------------------------- ### Companies House API OAuth 2.0 Authentication Flow Source: https://developer.company-information.service.gov.uk/authentication Provides an overview of the OAuth 2.0 authentication process for the Companies House API, detailing the developer setup steps and the initiation of the web server flow for end-user authentication and authorization. ```APIDOC OAuth 2.0 authentication: Overview: Interaction with some Companies House API functionality requires OAuth 2.0 authorisation. In web server apps, interaction with the Companies House API requires end-user involvement for authentication to prove their identity before the API will allow access. The Companies House API uses HTTP bearer access authentication to send an access token between the client application and the server. In a web server process flow, there must be end user involvement. The process flow is as follows: Developer setup: 1. The developer registers an application. 2. The developer then creates a web client for their application obtaining a client_id and a client_secret which must be stored securely by the developer. 3. The web server application must be configured to use this client_id and client_secret combination for interactions with the Companies House OAuth 2.0 service. Initiating the OAuth web server flow: 1. When the web server wants to sign an end user in with their Companies House account, it redirects the user's browser to the /oauth2/authorise endpoint with the developer's client_id and other details including the requested scopes and a registered redirect_uri. 2. The end user signs in to their Companies House account and provides a Company authentication code if any requested scopes contain a specific company number. 3. The end user will be prompted to grant access for the application to perform certain actions on their behalf. 4. When the end user grants this permission, they will be redirected to the redirect_uri provided with a code parameter to be used in the next stage. ``` -------------------------------- ### Perform a POST Request with JSON Body in REST API Source: https://developer.company-information.service.gov.uk/overview Illustrates how to use the HTTP POST method to create or modify a resource in a RESTful API. This example includes the HTTP request line, the Content-Type header indicating a JSON payload, and a sample JSON request body containing the data to be sent. ```HTTP POST https://api.example.domain/customer/12345 HTTP/1.1 ``` ```HTTP Content-Type: text/json ``` ```JSON { "CustomerName": "Joe Bloggs", "Address"     : "", "etc"         : "etc" } ``` -------------------------------- ### Characteristics of Public Data APIs Source: https://developer.company-information.service.gov.uk/api-testing Describes the nature of Public Data APIs, which are designed for reading existing data. These APIs primarily support GET requests and utilize basic API or stream key authorization. They can be safely tested in both live and sandbox environments. ```APIDOC Public Data APIs: - Purpose: Reading existing data (read-only) - HTTP Methods: GET requests only - Authorization: Basic API or stream key authorization - Testing Environment: Live or Sandbox ``` -------------------------------- ### Characteristics of Filing APIs Source: https://developer.company-information.service.gov.uk/api-testing Details the characteristics of Filing APIs, which allow for the creation, modification, and reading of data. These APIs support a combination of HTTP methods including POST, PUT, and PATCH, and require bearer OAuth access token authorization. Due to their data-altering nature, testing should exclusively be conducted in the sandbox environment. ```APIDOC Filing APIs: - Purpose: Create, change, and read data - HTTP Methods: POST, PUT, PATCH - Authorization: Bearer OAuth access token authorization - Testing Environment: Sandbox only ``` -------------------------------- ### Companies House Sandbox API URLs Source: https://developer.company-information.service.gov.uk/api-testing Provides the base URLs for the Companies House API, Identity service, and Test data generator when operating in the sandbox environment. These URLs must be used instead of live environment URLs for testing purposes. ```APIDOC API URL: https://api-sandbox.company-information.service.gov.uk Identity service URL: https://identity-sandbox.company-information.service.gov.uk Test data generator URL: https://test-data-sandbox.company-information.service.gov.uk (sandbox only) ``` -------------------------------- ### HTTP Basic Authentication with cURL Source: https://developer.company-information.service.gov.uk/authentication Demonstrates how to send an API key using HTTP Basic Authentication with a cURL command for the Companies House API, setting the Authorization header as defined by RFC2617. The API key is used as the username, and the password is left blank. ```shell curl -XGET -u my_api_key: https://api.company-information.service.gov.uk/company/00000006 ``` -------------------------------- ### API: Verify Access Token Source: https://developer.company-information.service.gov.uk/authentication Details the direct server-to-server request to the `/oauth/verify` endpoint to validate an access token before using it against other Companies House APIs. This verification is performed directly by the web server, not in the user's browser. ```APIDOC Endpoint: GET /oauth/verify Purpose: Verify the validity of an access token. Request Type: Server-to-server GET request. Parameters: Access token is typically passed in the Authorization header. Response: Indicates whether the token is valid. ``` -------------------------------- ### API: Exchange Authorization Code for Access Token Source: https://developer.company-information.service.gov.uk/authentication Describes the POST request to the `/oauth/token` endpoint from the web server to exchange an authorization code for `access_token` and `refresh_token`. This request is made directly from the server, not via a browser, and requires the `code`, developer's `client_id`, `client_secret`, and `grant_type` set to `authorization_code`. ```APIDOC Endpoint: POST /oauth/token Purpose: Exchange an authorization code for access and refresh tokens. Request Type: Server-to-server POST request. Required Parameters (in request body): - code: The authorization code obtained from the user's redirect. - client_id: Your application's client ID. - client_secret: Your application's client secret. - grant_type: Must be 'authorization_code'. Response: JSON object containing 'access_token' and 'refresh_token' upon success. ``` -------------------------------- ### API: Refresh Access Token Source: https://developer.company-information.service.gov.uk/authentication Explains how to use the `/oauth/token` endpoint with `grant_type` set to `refresh_token` to obtain a new access token when the current one expires. This allows the application to maintain continuous access without re-authenticating the user. ```APIDOC Endpoint: POST /oauth/token Purpose: Exchange a refresh token for a new access token. Request Type: Server-to-server POST request. Required Parameters (in request body): - refresh_token: The refresh token obtained previously. - client_id: Your application's client ID. - client_secret: Your application's client secret. - grant_type: Must be 'refresh_token'. Response: JSON object containing a new 'access_token' upon success. ``` -------------------------------- ### Perform a DELETE Request in REST API Source: https://developer.company-information.service.gov.uk/overview Shows how to use the HTTP DELETE method to remove a specific resource from a RESTful API endpoint. This method is used for resource deletion by targeting the resource's unique URI. ```HTTP DELETE https://api.example.domain/customer/12345 HTTP/1.1 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.