<!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>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>