Developing on Invoiced

OAuth

11min

This guide is designed for developers who aim to connect to the Invoiced API with OAuth 2.0 authentication. OAuth is a secure, industry-standard protocol for authorization. By the end of this document, you'll be equipped with the knowledge to implement OAuth authentication for interacting with the Invoiced API, ensuring secure access to your users' Invoiced data.

Prerequisites

Before you start, ensure you have the following:

  • An active Invoiced account.
  • Access to the Invoiced dashboard to create OAuth credentials.
  • A development environment capable of sending HTTP requests and handling responses.

If you are building an application in the sandbox environment then change all URLs from "invoiced.com" to "sandbox.invoiced.com".

Step 1: Register Your Application

To use OAuth authentication, you must first register your application in the Invoiced dashboard. This process will provide you with the Client ID and Client Secret necessary for the OAuth flow.

  1. Log in to your Invoiced account.
  2. Navigate to the Settings -> Developers page. Look for the OAuth Applications section.
  3. Register a new OAuth application. Fill in the required fields, such as the application name, and the callback URL. The callback URL is where the OAuth server will redirect after successful authentication.
  4. Save your application. After registration, you will receive a Client ID and Client Secret. Keep these credentials safe; they are crucial for the OAuth flow.

Step 2: Implementing OAuth Flow

OAuth authentication typically involves the following steps:

  1. Authorization Request: Direct the user to the Invoiced authorization URL, where they will log in and grant your application permission to access their account.
  2. Access Token Request: After authorization, use the provided authorization code to request an access token.
  3. API Request: Use the access token to make authenticated requests to the Invoiced API.

2.1 Authorization Request

Direct the user to the Invoiced authorization endpoint. Append the following query parameters:

  • response_type: This should be code.
  • client_id: The Client ID obtained during application registration.
  • redirect_uri: The same callback URL you provided during registration.
  • scope: The permissions your application requires. This value should be set to read_write or read.
  • state: To prevent CSRF attacks, add a unique token to confirm when the user returns to your website. This is optional.

Example authorization URL:

Text


2.2 Access Token Request

Once the user authorizes your application, they will be redirected to your redirect_uri with a code parameter. Use this code to request an access token by sending a POST request to the Invoiced token endpoint with the following parameters:

  • grant_type: This should be authorization_code.
  • code: The authorization code you received.
  • redirect_uri: Your callback URL.
  • client_id: Your Client ID.
  • client_secret: Your Client Secret.

Example request using cURL:

Curl


Example response:

JSON


2.3 API Request

Use the access token obtained in the previous step to make authenticated API requests. The access token must be included in the Authorization header as a Bearer token.

Example request using cURL:

Curl


Step 3: Handling Refresh Tokens

Access tokens are short-lived for security reasons. When an access token expires, use the refresh token (received along with the access token) to obtain a new access token without requiring the user to re-authorize your application.

Send a POST request to the token endpoint with:

  • grant_type: This should be refresh_token.
  • refresh_token: The refresh token you received.

Example request for a refresh token:

Curl


Conclusion

By following these steps, you can securely connect to the Invoiced API using OAuth authentication. This method ensures that your application can access only the data it is explicitly granted permission to, providing a secure and user-friendly way to integrate with Invoiced services.

Remember to keep your Client ID and Client Secret secure, regularly update your application's security practices, and adhere to the OAuth standard to maintain a secure integration with the Invoiced API.