<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>API</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="">
<meta name="keywords" content="">
<meta name="generator" content"JBake">
<!-- Le styles -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<link href="css/asciidoctor.css" rel="stylesheet">
<link href="css/base.css" rel="stylesheet">
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="js/html5shiv.js"></script>
<![endif]-->
<!-- Fav and touch icons -->
<!--<link rel="apple-touch-icon-precomposed" sizes="144x144" href="../assets/ico/apple-touch-icon-144-precomposed.png">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="../assets/ico/apple-touch-icon-114-precomposed.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="../assets/ico/apple-touch-icon-72-precomposed.png">
<link rel="apple-touch-icon-precomposed" href="../assets/ico/apple-touch-icon-57-precomposed.png">-->
<link rel="shortcut icon" href="favicon.ico">
</head>
<body>
<div id="wrap">
<nav class="navbar navbar-default" role="navigation">
<div class="container-fluid">
<div class="navbar-header">
<ul class="nav navbar-nav">
<li><a href=".">p4oauth</a></li>
<li><a href="overview.html">Overview</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="api.html">API</a></li>
<li><a href="development.html">Development</a></li>
<li><a href="../javadoc">Javadoc</a></li>
</ul>
</div>
</div>
</nav>
<div class="container">
<h1>P4OAuth API</h1><p>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.</p><p>You'll have to implement a redirect handler, however, that can retrieve authorization and p4d tokens, and generally know "what to do" with them.</p><h2>Fetch P4 Token</h2><p>Outside of the grant workflows is a basic "get me my p4d token for this whitelist" given a particular access token.</p><p>Send a GET request to the URL:</p>
<pre><code>https://p4oauth.perforce.com/p4token?redirect_uri=[WHITELISTED URL]&client_id=[LOGIN]
</code></pre><p>Required header:</p>
<pre><code>Authorization: Bearer A129380-123124-2312314
</code></pre><p>Required parameters:</p>
<ul>
<li><code>redirect_uri</code>: The whitelisted redirect URI</li>
<li><code>client_id</code>: The perforce user's login</li>
</ul><p>Optional parameter:</p>
<ul>
<li><code>state</code>: A custom application state variable, it's recommended to use this, probably something random</li>
</ul><p>This will return the P4D token via text.</p><h2>Password Authorization Grant</h2><p>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".</p>
<ol>
<li><p>The user starts at the client application, which collects the username and password</p></li>
<li><p>The client application posts this information to the P4OAuth "password grant" URL</p></li>
<li><p>The browser is redirected back to the client application with an authorization code</p></li>
<li><p>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.</p></li>
</ol><h4>Password Grant Request</h4><p>Make a POST request to this URL:</p>
<pre><code>http://p4oauth.example.com/grants/password
</code></pre><p>Required parameters:</p>
<ul>
<li><code>response_type</code> should be `password</li>
<li><code>client_id</code> - The perforce login</li>
<li><code>password</code> - The user's password</li>
<li><code>redirect_uri</code> - The whitelisted application URI we'll be redirecting back to</li>
</ul><p>Optional parameters:</p>
<ul>
<li><code>state</code> - If set, this will be sent back to the <code>redirect_uri</code>. Recommended.</li>
</ul><h4>Redirect</h4><p>After login, your client application will be called back with the following information:</p>
<pre><code>[WHITELISTED URL]?code=[AUTH CODE]
</code></pre><p>If you've added a <code>state</code> option, it will appear as another URL parameter.</p><h4>Access Token POST</h4><p><strong><em>This may change soon to include HTTP basic authentication</em></strong></p><p>Your application should take the <code>AUTH CODE</code> from the redirect, and generate the following POST request to this URL:</p>
<pre><code>https://p4oauth.example.com/grants/token
</code></pre><p>Required POST parameters:</p>
<ul>
<li><code>client_id</code> is the perforce login</li>
<li><code>redirect_uri</code> is the <strong>same</strong> URL used for the authorization start request for this authorization code</li>
<li><code>code</code> is the <code>AUTH CODE</code> sent to the client application's redirect handler</li>
<li><code>grant_type</code> must be set to <code>authorization_code</code></li>
</ul><p>The post will return a JSON response:</p>
<pre><code>{
"token_type": "bearer",
"access_token": "A129380-123124-2312314",
"perforce_token": "12983918247912875AH"
}
</code></pre>
<ul>
<li>The <code>token_type</code> will always be <code>bearer</code> for P4OAuth.</li>
<li><p>The <code>access_token</code> is a random string that should be put into the <code>Authorization</code> header of subsequent requests to P4OAuth or other Perforce services, like this:</p>
<pre><code>Authorization: Bearer A129380-123124-2312314
</code></pre></li>
<li><p>The <code>perforce_token</code> can be used for that machine directly</p></li>
</ul><h2>Code Authorization Grant</h2><p>The code authorization grant is intended for general web applications. The workflow involves a few redirects:</p>
<ol>
<li><p>The user starts at the client application, or "resource owner"</p></li>
<li><p>The user is redirected to the P4OAuth server</p>
<ul>
<li>The P4OAuth server will likely present a login page for the user to sign in with their Perforce credentials</li>
</ul></li>
<li><p>The user is redirected back to the client application</p>
<ul>
<li>At this point, the client application has received an "authorization code" that must be submitted back to the P4OAuth server</li>
<li>When the client application posts the authorization code back, it receives the access token, and, a P4 token for the registered client application host</li>
</ul></li>
</ol><p>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 <code>bearer</code> authorization header. Each other service will then use that token to retrieve the p4d token that has been provided for that host.</p><h4>Authorization Start Request</h4><p>Make a GET request to the authorization start URI:</p>
<pre><code>https://p4oauth.example.com/grants/authorization_code?response_type=code&client_id=[LOGIN]&redirect_uri=[WHITELISTED URL]
</code></pre><p>Required options:</p>
<ul>
<li><code>LOGIN</code> should be the Perforce username.</li>
<li><code>WHITELISTED URL</code> should be the exact URL registered in the whitelist for your client application</li>
</ul><p>It's recommended that clients add a <code>state</code> parameter to ensure that redirects back to the handler are double-checked.</p><h4>Redirect</h4><p>After login, your client application will be called back with the following information:</p>
<pre><code>[WHITELISTED URL]?code=[AUTH CODE]
</code></pre><p>If you've added a <code>state</code> option, it will appear as another URL parameter.</p><h4>Access Token POST</h4><p><strong><em>This may change soon to include HTTP basic authentication</em></strong></p><p>Your application should take the <code>AUTH CODE</code> from the redirect, and generate the following POST request to this URL:</p>
<pre><code>https://p4oauth.example.com/grants/token
</code></pre><p>Required POST parameters:</p>
<ul>
<li><code>client_id</code> is the perforce login</li>
<li><code>redirect_uri</code> is the <strong>same</strong> URL used for the authorization start request for this authorization code</li>
<li><code>code</code> is the <code>AUTH CODE</code> sent to the client application's redirect handler</li>
<li><code>grant_type</code> must be set to <code>authorization_code</code></li>
</ul><p>The post will return a JSON response:</p>
<pre><code>{
"token_type": "bearer",
"access_token": "A129380-123124-2312314",
"perforce_token": "12983918247912875AH"
}
</code></pre>
<ul>
<li>The <code>token_type</code> will always be <code>bearer</code> for P4OAuth.</li>
<li><p>The <code>access_token</code> is a random string that should be put into the <code>Authorization</code> header of subsequent requests to P4OAuth or other Perforce services, like this:</p>
<pre><code>Authorization: Bearer A129380-123124-2312314
</code></pre></li>
<li><p>The <code>perforce_token</code> can be used for that machine directly</p></li>
</ul>
</div>
</div><!-- #wrap -->
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="js/jquery-1.11.1.min.js"></script>
<script src="js/bootstrap.min.js"></script>
</body>
</html>