Ok, so that title should really read "Why and How..." since I plan on starting with the "Why" then moving to the "how", but I don't look backwards and neither should you. You're an engineer and you have code to write, and I have a blog to write. So, off we go!

The Why

Some API providers only allow you to use a single callback URL when using an OAuth flow. Why? I haven't the foggiest of ideas. That's the route they decided to go, so Cloud Elements implemented a way for you to use a single callback to service multiple environments. Let's say you have a single app for a Box integration your building. With that single app, you want to be able to hit both your testing and production environments. Well, out of the box (See what I did there) the provider does not allow that. So you can either spin up two apps, have environment variables in your code, and make a lot more work for yourself (Who has the time?). OR you can have one app with a proxy URL as the OAuth callback which has the ability to hit either environment. Your call, I'll wait while you decide...

I like you. You're still reading so I have to assume you want efficiency, not duplication. Smart.

The How

If you still want to/are being forced by your API provider into using an OAuth Proxy URL, please follow along and I'll show you how to set this up. If you read through everything, there is also a fun video at the end. Less birthday-party-fun and more... "OOOOO now I see what he means" kind-of-fun.

1. Choose your provider (for this example we are using Box)

2. Get basic info for your app like API key and secret. Don't fill in the redirect URL yet, we'll get to that in a bit.

3. Log into your Cloud Elements account: https://my-staging.cloudelements.io

4. In the lower left corner, click on the smiley face.

5. Take note of your Organization and User secrets, we will need these later.

6. Click on OAuth Proxy

7. Click on "Create New OAuth Proxy" and fill in name with something descriptive and click "Create". Don't worry about the API key and secret sections.

8. You should now have a unique URL generated by Cloud elements. Paste this in the Redirect URL in the provider's website (See I told you we'd deal with the Redirect URL later)

9. Now for the cURL GET command:

curl -X GET \
 'https://api.cloud-elements.com/elements/api-v2/elements/<Element name here>/oauth/url?isOauthProxy=true&oauthProxyName=%3CYour%20OAuth%20Proxy%20Name%3E&apiKey=%3CAPI%20Key%3E&apiSecret=%3CAPI%20Secret%3E&callbackUrl=%3CUnique%20UL%20Cloud%20Elements%20generated%3E&state=%3CURL%20you%20want%20the%20proxy%20to%20point%20to%3E&callbackProxy=true' \
 -H 'Authorization: User <secret>, Organization <secret>' \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' 




10. The above should either give you a code or have you run through the OAuth flow which will render a code to you. Regardless, grab that code.

11. Now we are going to create an instance by POSTing this:

curl -X POST \
https://api.cloud-elements.com/elements/api-v2/instances \
-H ‘Authorization: User <Secret>, Organization <sceret>’ \
-H ‘Cache-Control: no-cache’ \
-H ‘Content-Type: application/json’ \
-d ‘{
“element”: {
“key”: “<Name of Element>”
},
“providerData”: {
“code”: “<Code from the GET flow>”
},
“configuration”: {
“authentication.type”: “oauth2”,
“oauth.api.key”: “<Your API Key>“,
“oauth.api.secret”: “<Your API Secret>“,
“oauth.callback.url”: “<The OAuth Proxy URL Cloud Elements generated>”
},
“name”: “<Your name for the instance>”
}’

12. 
    

    12. With any luck you should get back a 200 response code and a brand-new instance of <insert Element name here>!

Way to go!

As promised here is the video.

OauthProxy from Ben Pepper on Vimeo.

P.S. The "configuration" JSON object for the POST may have to be slightly modified depending on the Element you are using. Refer to the authentication tab for the given Element here.