api.md #2

title=API
date=2014-06-05
type=page
status=published
~~~~~~

P4OAuth API
===========

The P4OAuth API provides a few different workflows. The exact calls you'll make varies generally with each workflow. You'll typically need to worry about the "fetch p4 token" workflow, and one of the grant workflows.

You'll have to implement a redirect handler, however, that can retrieve authorization and p4d tokens, and generally know "what to do" with them.




## Fetch P4 Token

Outside of the grant workflows is a basic "get me my p4d token for this whitelist" given a particular access token.

Send a GET request to the URL:

    https://p4oauth.perforce.com/p4token?redirect_uri=[WHITELISTED URL]&client_id=[LOGIN]

Required header:

    Authorization: Bearer A129380-123124-2312314

Required parameters:

* `redirect_uri`: The whitelisted redirect URI
* `client_id`: The perforce user's login

Optional parameter:

* `state`: A custom application state variable, it's recommended to use this, probably something random

This will return the P4D token via text.


## Password Authorization Grant

This grant is probably valid for P4OAuth since all of our applications must be put on a whitelist anyway for this thing to work. This allows the client application to collect the login and password, and submits those to the p4oauth server. The code authorization grant has the P4OAuth server collect this information "indirectly".

1. The user starts at the client application, which collects the username and password

2. The client application posts this information to the P4OAuth "password grant" URL

3. The browser is redirected back to the client application with an authorization code

4. The client application POSTs this authorization code back to the P4OAuth server, and receives the access token (which can be handed off to other apps) and a p4d token usable on that host only.

#### Password Grant Request

Make a POST request to this URL:

    http://p4oauth.example.com/grants/password

Required parameters:

* `response_type` should be `password
* `client_id` - The perforce login
* `password` - The user's password
* `redirect_uri` - The whitelisted application URI we'll be redirecting back to

Optional parameters:

* `state` - If set, this will be sent back to the `redirect_uri`. Recommended.

#### Redirect

After login, your client application will be called back with the following information:

    [WHITELISTED URL]?code=[AUTH CODE]

If you've added a `state` option, it will appear as another URL parameter.

#### Access Token POST

***This may change soon to include HTTP basic authentication***

Your application should take the `AUTH CODE` from the redirect, and generate the following POST request to this URL:

    https://p4oauth.example.com/grants/token

Required POST parameters:

* `client_id` is the perforce login
* `redirect_uri`  is the **same** URL used for the authorization start request for this authorization code
* `code` is the `AUTH CODE` sent to the client application's redirect handler
* `grant_type` must be set to `authorization_code`

The post will return a JSON response:

    {
        "token_type": "bearer",
        "access_token": "A129380-123124-2312314",
        "perforce_token": "12983918247912875AH"
    }

* The `token_type` will always be `bearer` for P4OAuth.
* The `access_token` is a random string that should be put into the `Authorization` header of subsequent requests to P4OAuth or other Perforce services, like this:

        Authorization: Bearer A129380-123124-2312314

* The `perforce_token` can be used for that machine directly



## Code Authorization Grant

The code authorization grant is intended for general web applications. The workflow involves a few redirects:

 1. The user starts at the client application, or "resource owner"

 2. The user is redirected to the P4OAuth server

     * The P4OAuth server will likely present a login page for the user to sign in with their Perforce credentials

 3. The user is redirected back to the client application

     * At this point, the client application has received an "authorization code" that must be submitted back to the P4OAuth server
     * When the client application posts the authorization code back, it receives the access token, and, a P4 token for the registered client application host

The access token is really all that the client application should maintain for the user. The client application can pass that access token around to other services using the `bearer` authorization header. Each other service will then use that token to retrieve the p4d token that has been provided for that host.

#### Authorization Start Request

Make a GET request to the authorization start URI:

    https://p4oauth.example.com/grants/authorization_code?response_type=code&client_id=[LOGIN]&redirect_uri=[WHITELISTED URL]

Required options:

* `LOGIN` should be the Perforce username.
* `WHITELISTED URL` should be the exact URL registered in the whitelist for your client application

It's recommended that clients add a `state` parameter to ensure that redirects back to the handler are double-checked.

#### Redirect

After login, your client application will be called back with the following information:

    [WHITELISTED URL]?code=[AUTH CODE]

If you've added a `state` option, it will appear as another URL parameter.

#### Access Token POST

***This may change soon to include HTTP basic authentication***

Your application should take the `AUTH CODE` from the redirect, and generate the following POST request to this URL:

    https://p4oauth.example.com/grants/token

Required POST parameters:

* `client_id` is the perforce login
* `redirect_uri`  is the **same** URL used for the authorization start request for this authorization code
* `code` is the `AUTH CODE` sent to the client application's redirect handler
* `grant_type` must be set to `authorization_code`

The post will return a JSON response:

    {
        "token_type": "bearer",
        "access_token": "A129380-123124-2312314",
        "perforce_token": "12983918247912875AH"
    }

* The `token_type` will always be `bearer` for P4OAuth.
* The `access_token` is a random string that should be put into the `Authorization` header of subsequent requests to P4OAuth or other Perforce services, like this:

        Authorization: Bearer A129380-123124-2312314

* The `perforce_token` can be used for that machine directly