Guides

Access Data on Behalf of Other Users with OAuth 2

Suggest Edits

At a glance

OAuth 2 authentication provides developers with a secure way to access Podium API data on behalf of other Podium users. Most commonly, OAuth 2 authentication is useful to set up integrations between third-party applications and Podium.

You might use OAuth 2 authentication to set up integrations that help you:

Sync your application data with Podium to keep invoices, reviews, feedback, and messages in sync.

In this guide, we’ll walk through how to set up OAuth 2 to authenticate users of your app, then demonstrate how to make a call to the API using an OAuth 2 access token.

Create your app

In order to communicate with Podium on behalf of a user, you will need to create an app in our developer portal.

📘

HTTPS

All requests to the Podium OAuth 2 endpoints are made over HTTPS. For security, we enforce using HTTPS for your redirect_uri.

Receive your Client ID and Client Secret for your app

Once the above information has been provided to Podium, your application is given an OAuth client_id and client_secret. These values are used throughout the rest of the OAuth flow.

OAuth 2 workflow overview
Even if you’ve used OAuth 2 in the past, workflows can differ slightly, so here’s a quick overview of Podium's OAuth 2 workflow:

When a user indicates that they allow you to authenticate with Podium on their behalf, your application will direct them to Podium's OAuth page, where they will log into their Podium account and authorize your application.

Podium will redirect the user back to your server with a query parameter named code; you’ll send that code in a request from your server to Podium, to exchange it for an access token. Access tokens are then added to requests to Podium's APIs in exchange for permission to call the API in behalf of the location(s).

1076

Podium OAuth 2 Flow

Get the authorization code

To get an authorization code, your app redirects the user to Podium's authorization endpoint.

Your request URL should look similar to the example below:

https://api.podium.com/oauth/authorize?client_id=<your_client_id>&redirect_uri=<your_redirect_uri>&scope=<your_requested_scopes>&state=<state>

Note the parameters that are being passed:

  • client_id. The Client ID of your application created above that is created in the developer portal. If you do not have a developer account, sign up at developer.podium.com.
  • redirect_uri. The callback location where the user agent is directed to along with the code. The redirect URI must match the URI that was set up when your application was first created.
  • scope. Associates the permissions granted by the user. View available OAuth scopes.
  • state. An arbitrary alphanumeric string that the Authorization Server reproduces when redirecting the user-agent back to the client. This is used to help prevent cross-site request forgery.

The passed client_id is the one issued to you from Podium. The passed redirect_uri must match the one provided when Podium set up your OAuth client.

📘

Multiple scopes

Multiple scopes must be separated with spaces as follows (note URL needs to be encoded): scope={{scope1}}%20{{scope1}}

Your user will follow this link to the Podium site and be presented with the permissions that your app is requesting. Once the user approves this request, they are redirected back via the Redirect URL that was provided with an authorization code parameter named code.

See response structure with authorization code:

https://your-site.com?code=<generated_authorization_code>&state=<state>

Redeem authorization code for access token

Once your authorization code has been generated, you can redeem it for an access_token with the Authorization URI:

https://api.podium.com/oauth/token

📘

Authorization API used for both access and refresh tokens

NOTE: the Authorization API is used to redeem an authorization code as well as refresh access tokens.

When redeeming an authorization code, it is required that you pass the following parameters:

  • client_id. (see description above)
  • client_secret. (see description above)
  • redirect_uri. (see description above)
  • grant_type. The type of request that is being made. NOTE: Must contain the string authorization_code. When redeeming a code for an access token.
  • code. The generated authorization code.

Example authentication request with authorization code

url --request POST \
  --url https://api.podium.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{"code":"de37f1997d3503d3fe23ac07687e34f0f","redirect_uri":"https://your-site.com","client_id":"fae50485-7774-4341-9e2c-43a1dc18021d","client_secret":"cd0fc846c371c09b58e86db14e30caf829d8c4a10f4c9c5d1d0db11b5503647c","grant_type":"authorization_code"}'

Granted access response

Responses will contain an access token and a refresh token. Access tokens expire after 10 hours, so your app will need to include logic to refresh access tokens if requests start failing due to expired tokens.

{
    "access_token": “eyJhbGciOiJSUzI1NiIsInR5cCI1IkpXVCJ9.eyJleHAiOjE1OTg0NjE5NTQsImtleSI8InVJaU1palhacWhsdXRoVktudnc2YXFKY2R0Q2VKWnNVMjRoVlA5RVJpS0VLY2RDQWVMUXRNNTNINkFqQjJjbGhDenBVTVl4b2plQ2ZldUZpZFNjWFFFdExnSTRid0JlbDlPL0JTM1lxdGJxazlxNDYzRmxYVmJ1ajlHU0dVeHdneGlBbUpiSCtrMUhWeTZrL0oyQWhpZ2gzUjBiZ3VMcmFQYTdnQmQ5UjRKN1NKWUNBK01Ib1FYclJuRGVhakZpZW1DamdibUZ3bklxdVl5L05tQUJpaXgxZy9QRS85SlI3NmRhMGRxSngrWHRVd1lmWG9NdzNaczZpREVMVHlCUHM4RmVZb3lkR2lzMk1qSlhkbmswcGJXSVBtVnpTRm9GS0h5dnRjMWRiT3RIOVRQRWM1RXhJK2NpWEJCWWx4c3NVQVVNYS91UktleDR0Y2cwZlJTbzhlZz09Iiwib2F1dGhfbWV0YWRhdGEiOiJWUVlscHFCZ2FIY0wwN2Uvb0s3WUd1K2RvOEdZTjVubXZzRFo2cTFERzhHUlRvdlNFRjAzT2tCYmhyNERad0E2WHZxaGN3UmhITVpJdjMyNWQ5Mk1xdW03OEphK1BlSUtQLzVCcklmV2NXNk9RVmJCbk1tT2YxU1QxYmo4Mk0yYTJNb3RmYnBlQ1FmanBxVXNJMUs5MjBFaUhGbnJ6M0NlYitGN3RHSnJPVnYvZjR5bmcreThLVkZKSG1UQ2Y3cHptZVZHQS8rOUlVWXUwd0FDSFR4NlhoNks2eFZpMWFLYmdySWRmUDlXZ2QxRzJRc3g1dlhXRmFGd0d3UXl6RGZ1UG5LTUVnN2k5Ly94RXBaMVZBR3dYSFNRVnlMR2gzWTRMbjc1VVk4L0F0Z0dQU04zbTNWRVVaTEhWUW5HbTFNZ05vdVRtOGRtbFp4SHNuczBHdjMxb2c9PSIsImV4cCI6MTU5ODQ5NjU4OCwiaWF0IjoxNTk4NDYwNTg4LCJqdGkiOiIyb25kdXJ0Y3FiY2swOGhrZDQwMDAwdTEiLCJuYmYiOjE1OTg0NjA1ODh9.ZRtjDHtsyK6c25YJEj_vsndgOAfRsXcOXrtm3Mg5yx9ha_sXfKujHtCtsE6GAt9SVg69J2_91tPkI8St3lz0BA”,
    "refresh_token": “7c9234163d5b5a2e480a9263fb789f027c2a8e4306c7f9c098c84ad1a2bb3c0”,
}

Refresh access token

When an access token has expired, the Authorization API should be used again with slight modifications.

When redeeming an authorization code, it is required that you pass the following parameters:

  • client_id. (see description above)
  • client_secret. (see description above)
  • grant_type. When refreshing an access token the grant type needs to be refresh_token.
  • refresh_token. You must use the refresh token returned when you first redeemed an OAuth code.

Example authentication request with the refresh token

curl --request POST \
  --url https://api.podium.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{"client_id":"fae50485-7774-4341-9e2c-43a1dc18021d","client_secret":"cd0fc846c371c09b58e86db14e30caf829d8c4a10f4c9c5d1d0db11b5503647c","grant_type":"refresh_token","refresh_token":"abe88d888b45f16f3b166af3343024c93d94eb607366a200e6a118e79316e9f9"}'

{
    "access_token": “TLwhbGciOiwSzzI1NiIsInR5cCI1IkpXVCw9.TLwlTHiiOwT1OTg2NwT5NTQsImtlTSI8InVwiz1pilhicWhsdXRoVktzdnc2LXFKL2R2Q2VKWnNVMwRoVli5RVwpS2VLL2RDQWVMzXRNNTNINkFqQwwwbGhDTnBVTVl4b2plQ2ZldzZpZFNwWFFFdTxnSTRid2wlbDlPL2wTM1lxdGwxizlxNDLzRmxLVmw1iwlHz2dVTHdnTGlBbzpiSCtrMzhWTTZrL2oLQWhpZ2gzzwBiZ3VMcmFQLTdnQmQ5zwRKN1NKWzNBK21Ib1FLclwzRGVhikZpZW1DimdibzZ3bklxdVl5L25tQzwpiXgxZL9QRS85SlI3NmRhMGRxSngrWHRVd1lmWG9NdzNiczZpRTVMVHlCzHM4RmVZb3lkR2lzMk1qSlhkbmswcGwXSVBtVnpTRm9GS2h5dnRwMWRiT3RIOVRQRWM1RXhwK2NpWTwCWWx4c3NVQVVNLS91zktlTDR2L2cwZlwTbzhlZz29Iiwib2F1dGhfbWV2LWRhdGTiOiwWzVlscHFCZ2FIL2wwN2zvb2s3Wzd1K2RvOTdZTwVzbXZzRFo2cTFTRzhHzlRvdlNFRwizT2tCLmhLNTRid2T2WHZxiGN3zmhITVpwdwMLNWQ5Mk1xdW23OTphK1BlSztQLzVCcklmV2NXNk9RVmwCbk1tT2Lxz1QxLmo4Mk2LLTwNb3RmLnBlQ1FminBxVXNwMzs5MwBFizhGbnw6M2NlLitGN3RHSnwPVnLvZwR5bmcrTThLVkZKSG1zQ2L3cHptZVZHQS8rOzlVWXzwd2FDSFR4NlhoNks2TFZpMWFLLmdLSWRmzDlXZ2QxRzwRc3g1dlhXRmFGd2d3zXl6RGZ1zG5LTzVnN2k5LL94RXBiMVZBR3dLSFNRVnlMR2gzWTRMbwc1VVk4L2F2Z2dQz24zbTNWRVViTThWzW5HbTFNZ25vdVRtOGRtbFp4SHNzczBHdwMxb2c9PSIsImV4cCI6MTz5ODQ5Nwz4OCwiiWF2IwoxNTk4NDLwNTg4LCwqdGkiOiILb25kdXw2L3FiL2swOGhrZDQwMDiwdTTiLCwzLmLiOwT1OTg2Nwi1ODh9.ZRtwDHtsLK6c25LwTw_vsndgOifRsXcOXrtm3Mg5Lx9hi_sXfKzwHtCtsT6Git9SVg69w2_91tPkI8St3lz2Bi”,
    "refresh_token": “abe88d888b45f16f3b166af3343024c93d94eb607366a200e6a118e79316e9f9”,
}

Updated almost 3 years ago

What’s Next