<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.sessions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" > <title>Sessions : Manage a Perforce Web API security token</title> <para> As covered in the <link linkend="chapter.client.programming">client programming guide</link>, authentication is handled using HTTP Basic Authentication, except that the password in the header can be a security token. These methods documented here handle the lifecycle of those security tokens. </para> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*" /> <colspec colname="description" colwidth="*" /> <thead> <row> <entry><para>Path</para></entry> <entry><para>Description</para></entry> </row> </thead> <tbody> <row> <entry><para><link linkend="api.sessions.v1_sessions_POST"> <literal>POST /v1/sessions</literal></link></para></entry> <entry><para>Creates a new security session token</para></entry> </row> <row> <entry><para><link linkend="api.sessions.v1_sessions_DELETE"> <literal>DELETE /v1/sessions</literal></link></para></entry> <entry><para>Deletes the token, making it unavailable for later use</para></entry> </row> </tbody> </tgroup> </informaltable> <section xml:id="api.sessions.v1_sessions_POST"> <title> <literal>POST /v1/sessions</literal> </title> <para> Creates a new security session with a token. </para> <para> Unlike most methods, this method does not require HTTP Basic Authentication. </para> <para> This method accepts a login with either a password or a Perforce ticket. </para> <para> Unlike most methods, this method returns a plaintext string to be used as the password for other calls to then authenticate as this user. </para> <simplesect xml:id="api.sessions.v1_sessions_POST.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry> <para>user</para> </entry> <entry> <para>The Perforce login</para> </entry> <entry> <para>string</para> </entry> <entry> <para>body</para> </entry> <entry> <para>Yes</para> </entry> </row> <row> <entry> <para>password</para> </entry> <entry> <para>The Perforce password or Perforce ticket</para> </entry> <entry> <para>string</para> </entry> <entry> <para>body</para> </entry> <entry> <para>Yes</para> </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.sessions.v1_sessions_POST.example"> <title>Example JSON request</title> <para> Example using the Perforce login <literal>jdoe</literal> whose password is<literal>pass123</literal>: </para> <programlisting language="json"> POST /v1/sessions HTTP/1.1 Content-Type: application/json { "user": "jdoe", "password": "pass123" }</programlisting> <para> This should respond with just a new token ID: </para> <programlisting> HTTP/1.1 200 OK Content-Type: text/plain;charset=utf-8 1b2e99b4-9a32-433a-960a-90b4cce458ca</programlisting> <para> From this point, that token should be combined with the user's password and base64 encoded to form the basic header: </para> <programlisting> Authorization: Basic amRvZToxYjJlOTliNC05YTMyLTQzM2EtOTYwYS05MGI0Y2NlNDU4Y2E=</programlisting> <para> This header then should be used on all authorized method calls to the rest of the API. </para> </simplesect> </section> <section id="api.sessions.v1_sessions_DELETE"> <title> <literal>DELETE /v1/sessions/[token]</literal> </title> <para> Deletes the token, making it unavailable for later use. </para> <para> This method requires authentication by the login that is associated with this token. </para> <para> There is no body with this request or response. </para> <simplesect id="api.sessions.v1_sessions_DELETE.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry> <para>token</para> </entry> <entry> <para>The Perforce Web API security token</para> </entry> <entry> <para>string</para> </entry> <entry> <para>path</para> </entry> <entry> <para>Yes</para> </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.sessions.v1_sessions_DELETE.example"> <title>Example</title> <para> The request should include an authorization header: </para> <programlisting> DELETE /v1/sessions/1b2e99b4-9a32-433a-960a-90b4cce458ca HTTP/1.1 Authorization: Basic amRvZToxYjJlOTliNC05YTMyLTQzM2EtOTYwYS05MGI0Y2NlNDU4Y2E=</programlisting> <para> The response should just indicate success or failure: </para> <programlisting> HTTP/1.1 200 OK</programlisting> </simplesect> </section> </chapter>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#2 | 13972 | tjuricek |
Removing old microservice implementations. The system is now mostly a monolith. Eventually there will be a websocket service. |
||
#1 | 13458 | tjuricek |
Revising P4 Web API docbook documentation to become the Perforce Web Services guide. Right now this is just focused on the Qt SDK. The remaining protocol documentation, etc, will happen eventually. |
||
//guest/perforce_software/helix-web-services/main/p4_web_api/p4_web_api/docbook/xml/methods/sessions.xml | |||||
#1 | 13412 | tjuricek |
Initial version of the web-services mainline. This is a collection of several projects, that will likely often get released together, though many of them may not always be relevant. See the README for more information. |