OAuth Connect

To create a 3rd party app or plugin that can access Payload accounts, Payload.js has a Connect function to trigger an OAuth authorization flow.

Connect Flow

Step 1) Request OAuth Code on Client

Pop-up example

<script src="https://payload.co/Payload.js"></script>

<script>
// See UI Authentication on how to obtain a client key
Payload('generated_client_token')

new Payload.Connect({
    org_id: 'org_f77fqR3fH4XUP8vEmqueOGOY',
    scope: 'org'
}).on('connected', function(e) {
    $.post('/get_payload_oauth_token', {code: e.code}, function(){
        alert('Connected!')
    })
})
</script>

Redirect example

<script>
new Payload.Connect({
    org_id: 'org_f77fqR3fH4XUP8vEmqueOGOY',
    scope: 'org',
    type: 'redirect',
    redirect_uri: 'http://example.com/redirect'
})
</script>

The first step is to initiate an OAuth authorization flow to obtain an authorization code. The resulting code will then be used to gain access to one or more processing accounts of an existing Payload user.

The simplest way to initiate a request for access is to use Payload.js Payload.Connect interface. Payload.Connect accepts org_id, scope, type, and redirect_uri.

Payload.Connect Parameters

Name	Description
`org_id`	The id of your primary payload organization
`scope`	`org` or `processing`
`type`	`null` or `redirect`
`redirect_uri`	If the `type` is `redirect` you must provide a `redirect_uri`
`auth_only`	Disable the sign up option within the OAuth flow

Step 2) Get Tokens on Server

curl "https://api.payload.co/oauth/token" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d code='<code retrieved from the client>' \
    -d grant_type=authorization_code \
    -d client_id='org_f77fqR3fH4XUP8vEmqueOGOY' \
    -d client_secret='secret_key_3bW9JMZtPVDOfFNzwRdfE'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@server.route('/get_payload_oauth_token', method='post')
def get_payload_oauth_token(code):
    resp = requests.post('https://api.payload.co/oauth/token', data=dict(
        code=code,
        grant_type='authorization_code',
        client_id='org_f77fqR3fH4XUP8vEmqueOGOY',
        client_secret='secret_key_3bW9JMZtPVDOfFNzwRdfE'
    ))

    # The resulting access token and refresh token
    do_something(resp.json()['access_token'], resp.json()['refresh_token'])
    return jsonify(1)

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

post '/get_payload_oauth_token/' do
    code = params[:code]

    resp = HTTParty.post("https://api.payload.co/oauth/token", body: {
        code: code,
        grant_type: 'authorization_code',
        client_id: 'org_f77fqR3fH4XUP8vEmqueOGOY',
        client_secret: 'secret_key_3bW9JMZtPVDOfFNzwRdfE'
    })

    do_something(resp['data']['access_token'], resp['data']['refresh_token'])
end

<?php
$code = $_POST['code'];
$ch = curl_init();

$fields = array(
    "code" => $code,
    "grant_type" => "authorization_code",
    "client_id" => "org_f77fqR3fH4XUP8vEmqueOGOY",
    "client_secret" => "secret_key_3bW9JMZtPVDOfFNzwRdfE"
);

curl_setopt($ch,CURLOPT_URL, "https://api.payload.co/oauth/token");
curl_setopt($ch,CURLOPT_POST, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);

$result = curl_exec($ch);

curl_close($ch);
?>

app.post('/get_payload_oauth_token', (req, res) => {
    var code = req.body.code
    axios.post('https://api.payload.co/oauth/token', {
        code: code,
        grant_type: 'authorization_code',
        client_id: 'org_f77fqR3fH4XUP8vEmqueOGOY',
        client_secret: 'secret_key_3bW9JMZtPVDOfFNzwRdfE'
    })
    .then((res) => {
      do_something(res.data.access_token, res.data.refresh_token)
    })
})

var token = await pl.OAuthToken.CreateAsync(new {
    code = "<code>",
    client_id = "org_f77fqR3fH4XUP8vEmqueOGOY",
    grant_type = "authorization_code",
    client_secret = "secret_key_3bW9JMZtPVDOfFNzwRdfE"
});

// The resulting access and refresh tokens
Console.WriteLine(token["access_token"]);
Console.WriteLine(token["refresh_token"]);

On the server side, you can use the oauth code returned from the client side to get the access token and refresh token.

Access tokens will only stay active temporarily, use the expires_in response value to determine how long until the token expires. To get a new token after expiration, see the next section on refreshing tokens with the refresh_token in this response.

Step 3) Refresh Access Token

curl "https://api.payload.co/oauth/token" \
    -d grant_type=refresh_token \
    -d refresh_token='<refresh token for user>'

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

@server.route('/refresh_payload_oauth_token', method='post')
def refresh_payload_oauth_token():
    resp = requests.post('https://api.payload.co/oauth/token', data=dict(
        grant_type='refresh_token',
        refresh_token='<refresh token for user>'
    ))

    # Store the resulting access token and refresh token
    do_something(resp.json()['access_token'], resp.json()['refresh_token'])
    return jsonify(1)

require 'payload'
pl = Payload::Session.new('secret_key_3bW9JMZtPVDOfFNzwRdfE')

post '/refresh_payload_oauth_token/' do
    resp = HTTParty.post("https://api.payload.co/oauth/token", body: {
        grant_type: 'refresh_token',
        refresh_token: '<refresh token for user>'
    })

    do_something(resp['data']['access_token'], resp['data']['refresh_token'])
end

<?php
$ch = curl_init();

$fields = array(
    "grant_type" => "refresh_token",
    "refresh_token" => "<refresh token for user>"
);

curl_setopt($ch,CURLOPT_URL, "https://api.payload.co/oauth/token");
curl_setopt($ch,CURLOPT_POST, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);

$result = curl_exec($ch);

curl_close($ch);
?>

app.post('/refresh_payload_oauth_token', (req, res) => {
    axios.post('https://api.payload.co/oauth/token', {
        grant_type: 'refresh_token',
        refresh_token: '<refresh token for user>'
    })
    .then((res) => {
      do_something(res.data.access_token, res.data.refresh_token)
    })
})

var token = await pl.OAuthToken.CreateAsync(new {
    grant_type = "refresh_token",
    refresh_token = "<refresh token for user>"
});

// The refreshed tokens
Console.WriteLine(token["access_token"]);
Console.WriteLine(token["refresh_token"]);

To refresh an expired token, simply pass the refresh token along with a grant_type=refresh_token to the /oauth/token endpoint. This will issue a new access_token and refresh_token.