Merge pull request #136 from packagist/api-authentication

API: extract authentication docs

Author: stevenrombauts

docs/api/api-authentication.md

@@ -0,0 +1,113 @@
+# API authentication
+##
+
+## Client library
+
+We provide a [php client](https://github.com/packagist/private-packagist-api-client) for the Private Packagist API.
+The client handles authentication, signature generation and access to all endpoints.
+
+Run `composer require private-packagist/api-client php-http/guzzle6-adapter` to install the client.
+
+### Basic usage
+```php
+$client = new \PrivatePackagist\ApiClient\Client();
+$client->authenticate('api-key', 'api-secret');
+$packages = $client->packages()->all();
+```
+
+## Authentication
+
+You can authenticate with the Private Packagist API using credentials, consisting of a public key and
+secret, that can be created in your organization settings under API Access. All API credentials are
+bound to a specific Private Packagist organization.
+
+API keys and secrets consists of three parts: a prefix, a random part, and an eight hexadecimal character long checksum.
+The prefix and checksum are designed to increase reliability of automatic scanning for secrets in your code base or leaked documents.
+These are the different prefixes:
+
+* `packagist_ack_`: API credential key
+* `packagist_acs_`: API credential secret
+
+### Supported headers
+
+The API expects a PACKAGIST-HMAC-SHA256 Authorization header to be present for every request.
+
+```
+Authorization: PACKAGIST-HMAC-SHA256
+Key=packagist_ack_ffce048835c6cdea47bcc4b73c79,
+Timestamp=1522925488,
+Cnonce=zjmfNVePGWoYksX/NJqnemb0g2dH30X3gu22JXqadZ0exBJsQZrC1xNYo10jyC6E,
+Signature=QXnRNGuXMOzd/dBnk1mbSUsA2M6ablgY+9y5/o/dIg4=
+```
+
+The required values are:
+
+* [Required] **Key**: "API key" part of your organization's API Access credentials
+* [Required] **Timestamp**: The unix timestamp of the current time when creating the request by the API caller. The timestamp is valid within 15 seconds of the server time when the request is processed.
+* [Required] **Cnonce**: The UUID generated by the API caller. This header is used with the time stamp to prevent replay.
+* [Required] **Signature**: Signature string. See below<
+
+### Signature verification
+
+The signature calculation procedure is as follows:
+
+#### Organize the strings involved in the signature calculation
+
+```php
+$params = [
+    'timestamp' => $time,
+    'cnonce' => $nonce,
+    'key' => $apiKey,
+];
+
+if ($content) {
+    $params['body'] => $content;
+}
+
+uksort($params, 'strcmp');
+
+$stringToSign =
+    $request->getMethod() . "\n" // all caps
+    . $request->getHost() . "\n" // api host
+    . $request->getPath() . "\n"
+    . http_build_query($params, '', '&', PHP_QUERY_RFC3986);
+```
+
+            
+Each letter of the HTTPMethod value must be capitalized.
+The body must only be set if the request body is not empty.
+            
+#### Calculate the signature
+
+```php
+$signature = base64_encode(
+    hash_hmac('sha256', $stringToSign, $secret, true)
+);
+```
+
+#### Pass the signature
+            
+The base64 encoded hash must be sent for every request with the **Authorization** header.
+
+#### Authentication and signature errors
+
+**HTTP 401**
+
+The API token sent with the **Authorization** header is invalid or missing.
+
+**HTTP 400**
+
+The signature validation sent with the **Authorization** header is invalid. Issues may be:
+
+* "Request must contain a signature.": **Signature** value is missing or empty
+* "Request must contain a timestamp.": **Timestamp** value is missing or empty
+* "Timestamp is beyond the +-15 second difference allowed.": **Timestamp** value is not valid.
+* "Invalid signature": **Signature** value does not match expected value
+
+### Accessing API endpoints without generating a signature
+                
+GET requests can also use a PACKAGIST-TOKEN Authorization header using your API key without generating a signature.
+
+```
+Authorization: PACKAGIST-TOKEN ffce048835c6cdea47bc
+```