NAME
WWW::Suffit::Server::API::V1 - The public Suffit API controller, version 1
SYNOPSIS
use WWW::Suffit::Server::API::V1;DESCRIPTION
The public Suffit API controller, version 1
METHODS
List of internal methods
authn
authz
public_key
API METHODS
List of API methods
POST /api/v1/authn
This method performs authentication of the remote user
# curl -v -H "Authorization: Bearer eyJh...Ggns" \
-X POST -d '{
"username": "bob",
"password": "bob",
"address": "1.2.3.4",
"encrypted": false
}' \
https://localhost:8695/api/v1/authn
> POST /api/v1/authn HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...Ggns
> Content-Length: 120
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Length: 30
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 10:18:22 GMT
< Server: OWL/1.11
<
{
"code": "E0000",
"status": true
}
# curl -v -H "Authorization: Bearer eyJh...Ggns" \
-X POST -d '{
"username": "bob",
"password": "incorrect",
"address": "1.2.3.4",
"encrypted": false
}' \
https://localhost:8695/api/v1/authn
> POST /api/v1/authn HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...Ggns
> Content-Length: 126
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 401 Unauthorized
< Content-Length: 74
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 10:22:11 GMT
< Server: OWL/1.11
<
{
"code": "E1326",
"message": "Incorrect username or password",
"status": false
}POST /api/v1/authz
This method performs authorization and checks access grants of the remote user
# curl -v -H "Authorization: Bearer eyJh...Ggns" \
-X POST -d '{
"username": "bob",
"method": "GET",
"url": "https://owl.localhost:8695/stuff",
"address": "1.2.3.4",
"headers": {
"Accept": "text/html,text/plain",
"Connection": "keep-alive",
"Host": "localhost:8695"
}
}' \
https://localhost:8695/api/v1/authz
> POST /api/v1/authz HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...Ggns
> Content-Length: 296
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Length: 30
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 10:40:17 GMT
< Server: OWL/1.11
<
{
"code": "E0000",
"status": true
}
# curl -v -H "Authorization: Bearer eyJh...Ggns" \
-X POST -d '{
"username": "bob",
"method": "GET",
"url": "https://localhost:8695/api/check",
"address": "1.2.3.4",
"verbose": true
}' \
https://localhost:8695/api/v1/authz
> POST /api/v1/authz HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...Ggns
> Content-Length: 166
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Length: 289
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 10:56:45 GMT
< Server: OWL/1.11
<
{
"address": "1.2.3.4",
"base": "https://localhost:8695",
"code": "E0000",
"email": "bob@example.com",
"email_md5": "4b9bb80620f03eb3719e0a061c14283d",
"expires": 1723633005,
"groups": [],
"method": "GET",
"name": "Bob Bob",
"path": "/api/check",
"role": "Test user",
"status": true,
"uid": 13,
"username": "bob"
}
# curl -v -H "Authorization: Bearer eyJh...Ggns" \
-X POST -d '{
"username": "unknown",
"method": "GET",
"url": "https://localhost:8695/api/check",
"address": "1.2.3.4"
}' \
https://localhost:8695/api/v1/authz
> POST /api/v1/authz HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...Ggns
> Content-Length: 145
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 401 Unauthorized
< Content-Length: 58
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 10:43:43 GMT
< Server: OWL/1.11
<
{
"code": "E1310",
"message": "User not found",
"status": false
}GET /api/v1/publicKey
Get RSA public key of user (of the token issuer)
# curl -v -H "Authorization: Bearer eyJh...Ggns" \
https://localhost:8695/api/v1/publicKey
> GET /api/v1/publicKey HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...Ggns
>
< HTTP/1.1 200 OK
< Content-Length: 306
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 11:02:33 GMT
< Server: OWL/1.11
<
{
"code": "E0000",
"public_key": "-----BEGIN RSA PUBLIC KEY-----...",
"status": true
}ERROR CODES
List of V1 Suffit API error codes
API | HTTP | DESCRIPTION
-------+-------+-------------------------------------------------
E1100 [404] No RSA public key found
E1101 [400] No RSA private key found
E1102 [500] RSA decrypt error
E1103 [ * ] Incorrect username or password
E1104 [ * ] Access denied (authz)
E1105 [ * ] Access denied by realm restrictions (access)
E1106 [---] Reserved
E1107 [---] Reserved
E1108 [---] Reserved
E1109 [---] Reserved* -- this code will be defined later on the interface side
See also list of common Suffit API error codes in "ERROR CODES" in WWW::Suffit::API
HISTORY
See Changes file
TO DO
See TODO file
SEE ALSO
Mojolicious, WWW::Suffit, WWW::Suffit::Server, WWW::Suffit::API
AUTHOR
Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>
COPYRIGHT
Copyright (C) 1998-2024 D&D Corporation. All Rights Reserved
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See LICENSE file and https://dev.perl.org/licenses/