OAuth 2.0 walkthrough
You can choose to restrict Pennylane access based on a specific user access, thus linking your Token with a specific user and a specific company.
To do so, we use OAuth 2.0, an industry-standard protocol. It allows our application to access specific user data without requiring a private user's credentials. A good representation of the protocol can be found here
Register your application
Register your app with Pennylane
In order to connect to Pennylane via OAuth 2.0, your app must be registered. To ask to be registered, you can fill the form available here.
⚠️ If you are willing to become an integration partner, you need to be validated by our partnerships team through this form first !
We will validate your demand and assign you a specific Client Id and Client Secret. The Client Secret should not be shared.
Once registered, you app will be able to ask for specific permission scopes and will be rewarded with an access token upon a user's approval. An access token is linked to a specific user and to a specific company.
Step 1 : "Sign in with Pennylane" button
Once you get your client id and client secret, you can include in your app a "Sign in with Pennylane" button. This button should redirect users to the following URL : https://app.pennylane.com/oauth/authorize. The following parameters should be passed as GET parameters:
| Parameter | Required | Description |
|---|---|---|
| client_id | yes | Id provided by Pennylane once your app is registered |
| redirect_uri | yes | URL to redirect to after user approval (whether successful or not) |
| response_type | yes | Type of authentication flow. Must be code. |
| state | no | A security parameter. A unique string that is sent back to you at the end of the authentication process. |
| scope | yes | The scope you want to have access to. If you add multiple scopes, use + as a delimiter. |
Important: All parameters in the request, including the redirect_uri, state, and any others that might contain special characters or spaces, must be URL encoded. This ensures that your request is correctly processed by our API.
Example of a valid URL with proper URL encoding:
Once loaded, the page will ask the logged user to pick one of his accessible companies.
Step 2 : Users are redirected with an authorization code
After getting the user's approval to authorize your app, Pennylane will redirect the user to the redirect_uri you provided with an authorization code GET parameter and the state parameter if you provided one in the previous state. You should compare the received state with the one you provided. If they don't match, the request may have been compromised, you should abort the process.
Step 3 : Exchange Authorization Code <=> Bearer Token
Once you compared the state, you can exchange the authorization code provided in step 1 with an actual bearer token. To do so, you should make a POST request on https://app.pennylane.com/oauth/token. The following parameters should be passed as body parameters:
| Parameter | Required | Description |
|---|---|---|
| client_id | yes | Id provided by Pennylane once your app is registered |
| client_secret | yes | Client Secret provided by Pennylane once your app is registered |
| code | yes | The code received in step 2. |
| redirect_uri | yes | URL to redirect to once our server handled your request (whether successful or not) |
| grant_type | yes | Must be authorization_code at this step. Only authorization_code and refresh_token are currently supported |
If the client_id / client_secret / code are all valid, Pennylane will send you a JSON response containing an access_token, an expiration date and a refresh_token. You must store the access_token and the refresh_token.
Note: You can only use the code once to retrieve the tokens.
{
"access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}
Refreshing the token
Once the access_token has reached its expiration date, you won’t be able to access Pennylane anymore. You'll need to request a new one through a POST request at https://app.pennylane.com/oauth/token.
The following parameters should be passed as body parameters:
| Parameter | Required | Description |
|---|---|---|
| client_id | yes | Id will be provided by Pennylane once you ask us to register your application |
| client_secret | yes | Client Secret will be provided by Pennylane once you ask us to register your application |
| refresh_token | yes | The refresh token provided by Pennylane once you create the access_token |
| grant_type | yes | Must be refresh_token at this step. Only authorization_code and refresh_token are supported |
Revoking the token
To ensure the security of user data and respect user privacy, it's crucial to invalidate an access token when it's no longer needed. This could be when your application has completed its intended interaction with the user's data, or if the user decides to withdraw your application's access. Revoking a token promptly helps prevent unauthorized access and potential security breaches.
To do so, you should perform a POST request to http://app.pennylane.com/oauth/revoke with the following body parameters:
| Parameter | Required | Description |
|---|---|---|
| client_id | yes | Id will be provided by Pennylane once you ask us to register your application |
| client_secret | yes | Client Secret will be provided by Pennylane once you ask us to register your application |
| token | yes | The token you want to revoke |
Upon successful revocation, the endpoint will respond with HTTP status code 200 OK and an empty response body.
Updated 6 months ago