87 lines
2.1 KiB
Markdown
87 lines
2.1 KiB
Markdown
# 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 |