/ 
WWW-Suffit-API-1.03
River stage zero No dependents
/ WWW::Suffit::Server::API::User

NAME

WWW::Suffit::Server::API::User - The Suffit API controller for user management

SYNOPSIS

use WWW::Suffit::Server::API::User;

DESCRIPTION

The Suffit API controller for user management

This module uses the following configuration directives:

JWS_Algorithm

Allowed JWS signing algorithms: HS256, HS384, HS512, RS256, RS384, RS512

HS256   HMAC+SHA256 integrity
HS384   HMAC+SHA384 integrity
HS512   HMAC+SHA512 integrity
RS256   RSA+PKCS1-V1_5 + SHA256 signature
RS384   RSA+PKCS1-V1_5 + SHA384 signature
RS512   RSA+PKCS1-V1_5 + SHA512 signature

Default: HS256

METHODS

List of internal methods

genkeys

See "POST /api/user/genkeys"

passwd

See "PATCH /api/user/passwd"

token_del

See "DELETE /api/user/token/JTI"

token_get

See "GET /api/user/token"

token_set

See "POST /api/user/token"

user_get

See "GET /api/user"

user_set

See "PUT /api/user"

API METHODS

List of API methods

GET /api/user

This method returns user data

# curl -v -H "Authorization: Bearer eyJh...s5aM" \
  https://localhost:8695/api/user

> GET /api/user HTTP/1.1
> Host: localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: Bearer eyJh...s5aM
>
< HTTP/1.1 200 OK
< Content-Length: 653
< Content-Type: application/json;charset=UTF-8
< Date: Wed, 14 Aug 2024 16:33:34 GMT
< Server: OWL/1.11
<
{
  "algorithm": "SHA256",
  "attributes": "",
  "code": "E0000",
  "comment": "Test user for internal testing only",
  "created": 1678741533,
  "email": "test@owl.localhost",
  "email_md5": "163e50783979333ebae6fd63b2d96d16",
  "expires": 0,
  "flags": 31,
  "groups": [
    "user"
  ],
  "name": "Test User",
  "not_after": 0,
  "not_before": 1695334721,
  "public_key": "-----BEGIN RSA PUBLIC KEY-----...",
  "role": "Test user",
  "status": true,
  "uid": 3,
  "username": "test"
}

PUT /api/user

Edit user's data

# curl -v -H "Authorization: OWL eyJh...04qI" \
  -X PUT -d '{
    "name": "Test User",
    "email": "test@owl.localhost",
    "role": "Test user",
    "comment": "Test user for internal testing only"
  }' \
  https://owl.localhost:8695/api/user

> PUT /api/user HTTP/1.1
> Host: owl.localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: OWL eyJh...04qI
> Content-Length: 163
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Length: 148
< Server: OWL/1.00
< Date: Mon, 15 May 2023 11:25:11 GMT
< Content-Type: application/json;charset=UTF-8
<
{
  "comment": "Test user for internal testing only",
  "email": "test@owl.localhost",
  "name": "Test User",
  "role": "Test user",
  "status": true,
  "username": "test"
}

POST /api/user/genkeys

Issue (generation) RSA keys pair (public and private RSA keys) for user

# curl -v -X POST -H "Authorization: OWL eyJh...R_0c" \
  https://owl.localhost:8695/api/user/genkeys

> POST /api/user/genkeys HTTP/1.1
> Host: owl.localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: OWL eyJh...R_0c
>
< HTTP/1.1 200 OK
< Date: Fri, 12 May 2023 06:31:21 GMT
< Server: OWL/1.00
< Content-Type: application/json;charset=UTF-8
< Content-Length: 1228
<
{
  "error": "",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----...",
  "public_key": "-----BEGIN RSA PUBLIC KEY-----",
  "status": true
}

PATCH /api/user/passwd

Change password for user

# curl -v -H "Authorization: OWL eyJh...Bh7g" \
  -X PATCH -d '{
    "current": "currentPassword",
    "password": "newPassword"
  }' \
  https://owl.localhost:8695/api/user/passwd

> PATCH /api/user/passwd HTTP/1.1
> Host: owl.localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: OWL eyJh...04qI
> Content-Length: 64
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Server: OWL/1.00
< Content-Type: application/json;charset=UTF-8
< Content-Length: 30
< Date: Mon, 15 May 2023 11:36:50 GMT
<
{
  "code": "E0000",
  "status": true
}

DELETE /api/user/token/JTI

Removes specified token from list of tokens for user of current session

# curl -v -X DELETE -H "Authorization: OWL eyJh...04qI" \
  https://owl.localhost:8695/api/user/token/SqpHCfCS2646efd7

> DELETE /api/user/token/SqpHCfCS2646efd7 HTTP/1.1
> Host: owl.localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: OWL eyJh...04qI
>
< HTTP/1.1 200 OK
< Server: OWL/1.00
< Content-Type: application/json;charset=UTF-8
< Content-Length: 30
< Date: Mon, 15 May 2023 11:11:35 GMT
<
{
  "code": "E0000",
  "status": true
}

GET /api/user/token

Get list of tokens for user of current session

# curl -v -X GET -H "Authorization: OWL eyJh...04qI" \
  https://owl.localhost:8695/api/user/token

> GET /api/user/token HTTP/1.1
> Host: owl.localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: OWL eyJh...04qI
>
< HTTP/1.1 200 OK
< Server: OWL/1.00
< Date: Mon, 15 May 2023 11:02:33 GMT
< Content-Length: 491
< Content-Type: application/json;charset=UTF-8
<
[
  {
    "address": "127.0.0.1",
    "clientid": "b048c047a0f0165ab7630f7aab1cb5aa",
    "exp": 1684227656,
    "iat": 1684141256,
    "id": 88,
    "jti": "ke2uj4ib059db017",
    "type": "session",
    "username": "test",
    "description": ""
  }
]

POST /api/user/token

Issues the new API token for user of current session by session or access token

# curl -v -X POST -H "Authorization: OWL eyJh...aMTc" \
  https://owl.localhost:8695/api/user/token

> POST /api/user/token HTTP/1.1
> Host: owl.localhost:8695
> User-Agent: curl/7.68.0
> Accept: */*
> Authorization: OWL eyJh...aMTc
>
< HTTP/1.1 200 OK
< Server: OWL/1.00
< Content-Type: application/json;charset=UTF-8
< Content-Length: 586
< Date: Fri, 12 May 2023 05:42:37 GMT
<
{
  "address": "127.0.0.1",
  "clientid": "f459f12619c961122450ae5883e44a60",
  "exp": 0,
  "iat": 1683870157,
  "id": 87,
  "jti": "SqpHCfCS2646efd7",
  "status": true,
  "token": "eyJh...H8ac",
  "type": "api",
  "username": "test",
  "description": ""
}

ERROR CODES

The list of User Suffit API error codes

 API   | HTTP  | DESCRIPTION
-------+-------+-------------------------------------------------
 E1120   [400]   Incorrect username
 E1121   [400]   Incorrect current password
 E1122   [400]   Incorrect new password
 E1123   [500]   Can't generate RSA keys
 E1124   [500]   Can't JWT generate
 E1125   [500]   Can't token store to database
 E1126   [400]   Incorrect JWT jti
 E1127   [500]   Can't delete token from database
 E1128   [500]   Can't edit user data (user_set)
 E1129   [500]   Can't change user password
 E1130   [500]   Can't save RSA keys to database

* -- 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-2025 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/