OAuth 2.0 overview
The Bigin API utilizes the OAuth 2.0 protocol for authorization. The open standard authorization protocol provides a secure connection between third-party applications and Bigin. The OAuth 2.0 specification enables third-party applications (also known as clients) to obtain delegated permissions for accessing protected resources (data) in Bigin using APIs on behalf of Bigin users and with their authorization.
Instead of a traditional username and password, the OAuth 2.0 protocol uses an access token with the API request to read, create, update, and delete data in the resource server. Bigin uses Authorization Code Grant Type for obtaining an access token. That is, the access token is obtained in exchange for an authentication code with the authorization server.
In order to understand the OAuth 2.0 protocol in detail, let's first get familiar with the common terminology used in the OAuth 2.0 flow.
- Protected resources - The available resources in your Bigin account, such as Team Pipelines, Sub-pipelines, Contacts, Companies, Notes etc.
- Resource server - The server hosting and managing the protected resources. In this case, Bigin server.
- Resource owner - Any entity within your account who is capable of delegating protected resource access to the client. Here, the entity is referred to as an end-user of Bigin.
- Client - An application that makes requests to the resource server for accessing protected resources on behalf of the resource owner and with their authorization. In Bigin's OAuth 2.0 implementation, the term client is common to all types of clients such as client-based applications, server-based applications, mobile-based applications, non-browser applications and self-client.
- Client ID - The client identifier that is obtained when you register your client with an authorization server.
- Client Secret - A secret key that is obtained when you register your client with an authorization server. It helps the server to identify your client.
- Authorization server - The server that provides access tokens after successfully validating the client credentials and obtaining the resource owner's consent.
- Authorization code - A short-lived code that is obtained through the user-agent (browser) when the resource owner provides consent to the client's request for accessing their resources. Further, it's used to generate access and refresh tokens.
- Redirect URI - A callback URI to which the authorization server sends the user-agent (browser) back once the resource owner accepts or denies the access request.
- Access tokens - A temporary key token obtained from the authorization server that is used as a credential for accessing protected resources.
- Refresh tokens - A key token obtained along with an access token and used to generate a new access token.