# ucenter simple authentication API

## cURL
```shell
curl -X POST \
-H 'Content-Type: application/json; charset=UTF-8'\
-H 'Client-ID: <uuid>'\
-H 'Authorization: Bearer <key>'\
-H 'Accept: application/json'\
-d '{"account": "<account>", "password": "<password>"}'\
https://example.com/api/2nd-part-app/v1/simple-authenticate
```
 - `<uuid>` Application's uuid
 - `<key>` Application's client secret
 - `<account>` User's account name, not an email address (user credential)
 - `<password>` User's password (user credential)

### Example

```shell
curl -X POST \
-H 'Content-Type: application/json; charset=UTF-8'\
-H 'Client-ID: 2467aff9-5f65-4860-86db-eef597ec3eb6'\
-H 'Authorization: Bearer uuhC1j21nyXhiJfuuluZGmI72n6a8PLkYHn49jY67X7EyGcpLyIgPz7zYTEL'\
-H 'Accept: application/json'\
-d '{"account": "testUser", "password": "userSecret"}'\
https://example.com/api/2nd-part-app/v1/simple-authenticate
```

## PHP example

### Setup project

```shell
composer install
```

### Run

```shell
php src/example.php
```

## API Result

### Success

Response status code is 200 OK.
Content could be a JSON as following:

```json
{
  "ok": true,
  "error": null,
  "message": "Credential is valid",
  "result": true
}
```
 - `ok` *boolean* API is called and running without error
 - `error` *string* (Not used in this API) detail error code
 - `message` *string* Human-readable message
 - `result` *boolean* Authentication result, `true` if user credential is correct, `false` if user not found or wrong credential

The field `result` is good to indicate the user credential correctness.

### Failed

Response status code is still 200 OK. **(Important! Not 401 or 403)** 
But the content could be a JSON as following:

```json
{
  "ok": true,
  "error": null,
  "message": "Credential is invalid or user was suspended",
  "result": false
}
```

### Other response

List all probable status code:
 - `401` Client UUID or client secret is wrong
 - `403` Your client is not allowed to call this API, you need to ask the system administrator for more permission
 - `404` Wrong URL to the API endpoint
 - `422` User credential format is bad
 - `429` Exceed the rate limit