Authentication via OAuth2.0¶
1. Introduction¶
You can now access the Copper Developer API via OAuth2.0. This authentication method is an alternative to Copper's legacy API Keys, and is particularly well-suited for third-party integrations looking to create a seamless and secure link between their users and Copper.
OAuth2.0 offers several advantages over the API Key flow:
- Authentication is open to all users, not just administrators
- No need to generate and copy API keys from Copper to your application
- Readily available client libraries help with smooth integration
2. Prerequisites¶
To use OAuth2.0 with Copper, you must first register your application. This step protects requests from forgery and keeps your users secure.
To register your application, contact us. You will need to provide the name and purpose of your application as well as a URL to an HTTPS endpoint that will handle the secure callback.
You will receive two credentials, client_id and client_secret, required for all authorization flows.
| Parameter | Description |
|---|---|
| client_id | A public alphanumeric string that uniquely identifies your application |
| client_secret | A private alphanumeric secret that verifies your application's identity |
| redirect_uri | The callback endpoint of your application (e.g. https://yourapp.com/callback) |
3. Authorization Flow Overview¶
Copper implements the commonly-used Authorization Code Grant flow:
- Your application initiates the authorization flow by directing the user to Copper's authorization endpoint
- The user then logs into their Copper account, and accepts the permission scopes requested by your application
- The user is then redirected back to your application with a temporary authorization code
- Lastly, your application exchanges this code for an access token, which can be used to query Developer API endpoints
For more details, click here.
4. Quickstart Guide¶
Follow our quickstart guide to get up and running quickly.
5. Documentation¶
The detailed Copper authorization flow documentation can be found here.
6. Access Token Management¶
Active OAuth2.0 connections are shown in the Copper user interface, under Settings ➡ Integrations ➡ Active Integrations. This interface also lets users revoke their tokens.
Note: account administrators may revoke tokens on behalf of other users
7. Scopes¶
Scopes define specific permissions your application wants to obtain from the user. Currently,
only the developer/v1/all scope is supported, which grants full read and modify access to the authenticated user's records.
This scope is backward compatible with our legacy API Key authentication.
| Scope | Permissions |
|---|---|
| developer/v1/all | Read and modify user records |
Note: more granular scopes will be added in the future
8. Client Libraries¶
Although it's entirely feasible to implement the OAuth 2.0 flow through plain REST, it's advisable to leverage a library tailored to your chosen application language or framework.
| Language | Library |
|---|---|
| Python | requests-oauthlib |
| Java | Spring Security OAuth |
| JavaScript (Node.js) | simple-oauth2 |
| Ruby | omniauth, oauth2 |
| PHP | league/oauth2-client |
| C# (.NET) | DotNetOpenAuth |
| Go (Golang) | golang/oauth2 |
| Swift (iOS/macOS) | OAuthSwift |