Accounting

Accounts

Luna-API supports a data separation by accounts. An account is needed to delimit the visibility areas of objects for a particular user. Each created account has its own unique “account_id”. All data created by this account is stored in the Accounts database under this identifier.

When creating the account, you need to specify the following data: login (email), password and account type. The account type determines what data is available to the user. There are three types of accounts:

• user - user who can create objects and use only the data of his account.

• advanced_user - user who has rights same to user and also has access to the data of all accounts. Access to other accounts data means being able to get data (GET requests), check for its existence (HEAD requests) and perform matching requests by data of other accounts.

• admin - administrator who has rights same to advanced_user and also has access to the Admin service. Administrator account creation is impossible using Luna-API. To create administrator account use Luna-Admin service.

By default, there is the account in the system with the admin type and default login and password root@visionlabs.ai/root.

Restrictions on performed requests for all types of accounts are hard-coded in the system and cannot be changed. If you require restrictions other than the standard ones, you should create the “user” account and then create a token and configure the restrictions as required.

Tokens

The token is linked to the existing account and enables you to impose extended restrictions on performed requests. For example, when creating the token, you can give the user permission to only create and modify lists and faces, or you can prohibit the use of certain handlers by specifying their ID.

Note

See token coverage table for specific resources in the Token permissions section.

The token is created for a certain period of time (the token expiration time can be infinite).

Using the token, you can also control the visibility area of other accounts data using the “visibility_area” parameter (all - data of all accounts, account - data of this account only). For the user account type, you cannot set “visibility_area” = “all”.

Authorization to access resources

To make requests to Luna-API resources, authorization should be specified.

There are three types of authorization:

• BasicAuth. Authorization by login and password (set during account creation).

• BearerAuth. Authorization by JWT token (issued after the token is created).

• LunaAccountIdAuth. Authorization by “Luna-Account-Id” header, which specifies the “account_id” generated after creating the account (this type of authorization was used as the only one until LP version v.5.29.0).

There is no need to use all three types of authorization when making requests. It is necessary to choose the preferred method depending on the required tasks.

Note

Authorization type LunaAccountIdAuth has the lowest priority compared to other types and marked as Deprecated in the OpenAPI specification. You can disable authorization of the LunaAccountIdAuth type using the ALLOW_LUNA_ACCOUNT_AUTH_HEADER setting. The setting is enabled by default.

When using the LunaAccountIdAuth, the visibility area is controlled using the Luna-Account-Id header, i.e. only the data of the account associated with this ID is visible.

If the authorization type is not specified in the request, an error with the status code 403 will be issued.

Token permissions

The following table describes token permissions for Luna-API resources

route	method	token permissions
/6/tokens	post	token - creation
	get	token - view
/6/tokens/{token_id}	put	token - modification
	get	token - view
	delete	token - deletion
/6/sdk	post	resource - sdk
/6/iso	post	resource - iso
/6/samples/faces	post	faceSample - creation
/6/samples/faces/{sample_id}	get	faceSample - view
	head	faceSample - view
	delete	faceSample - deletion
/6/samples/bodies	post	bodySample - creation
/6/samples/bodies/{sample_id}	get	bodySample - view
	head	bodySample - view
	delete	bodySample - deletion
/5/samples/{sample_id}	get	faceSample - view
	head	faceSample - view
	delete	faceSample - deletion
/6/samples/{sample_id}	get	faceSample - view
	head	faceSample - view
	delete	faceSample - deletion
/6/extractor	post	attrbiute - creation
/6/attributes	post	attribute - creation
	get	attribute - view
/6/attributes/{attribute_id}	get	attribute - view
	head	attribute - view
	delete	attribute - deletion
/6/attributes/{attribute_id}/samples	get	attribute - view
/6/faces	post	face - creation & list - modification *1
	get	face - view
	delete	face - deletion
/6/faces/count	get	face - view
/6/faces/attributes/count	get	attribute - view
/6/faces/{face_id}	get	face - view
	patch	face - modification
	delete	face - deletion
	head	face - view
/6/faces/{face_id}/attributes	put	face - creation
	get	face - view
	delete	face - deletion
/6/faces/{face_id}/attributes/samples	get	faceSample - view
/6/lists	post	list - creation *2
	get	list - view
	delete	list - deletion *2
/6/lists/count	get	list - view
/6/lists/{list_id}	get	list - view
	head	list - view
	patch	list - modification
	delete	list - deletion
/6/lists/{list_id}/faces	patch	list - modification
/6/matcher/faces	post	face/event/attribute - matching *3
/6/matcher/bodies	post	event - matching *4
/6/handlers	post	handler - creation
	get	handler - view
/6/handlers/count	get	handler - view
/6/handlers/{handler_id}	get	handler - view
	put	handler - modification
	head	handler - view
	delete	handler - deletion
/6/handlers/{handler_id}/events	post	event - emit_events *5
/6/handlers/{handler_id}/stream_events	post	event - emit_events *5
/6/handlers/{handler_id}/events/raw	post	event - creation
/6/events/statistic	post	event - view
/6/events	get	event - view
/6/events/{event_id}	get	event - view
	head	event - view
/6/tasks/clustering	post	task - creation
/6/tasks/reporter	post	task - creation
/6/tasks/exporter	post	task - creation
/6/tasks/linker	post	task - creation
/6/tasks/gc	post	task - creation
/6/tasks/cross_match	post	task - creation
/6/tasks/roc	post	task - creation
/6/tasks/estimator	post	task - creation
/6/tasks	get	task - view
/6/tasks/count	get	task - view
/6/tasks/{task_id}	get	task - view
	patch	task - modification
	delete	task - deletion
/6/tasks/{task_id}/result	get	task - view
/6/tasks/{task_id}/subtasks	get	task - view
/6/tasks/{task_id}/errors	get	task - view
/6/tasks/errors	get	task - view
/6/tasks/errors/count	get	task - view
/6/tasks/errors/{error_id}	get	task - view
/6/verifiers	post	verifier - creation
	get	verifier - view
/6/verifiers/count	get	verifier - view
/6/verifiers/{verifier_id}	get	verifier - view
	put	verifier - modification
	head	verifier - view
	delete	verifier - deletion
/6/liveness	post	resource - liveness
/6/images	post	image - creation
/6/images/{image_id}	get	image - view
	head	image - view
	delete	image - deletion
/6/objects	post	object - creation
/6/objects/{object_id}	get	object - view
	head	object - view
	delete	object - deletion

*1 - face creation request requires list modification permission if one or more lists specified in request body

*2 - list/lists deletion requests requires face deletion permissions if with_faces parameter specified

*3 - face matching request requires face/event/attribute matching permissions if face/event/attribute candidates/references specified in request body

*4 - body matching request requires event matching permissions if event candidates/references specified in request body

*5 - The “emit_events” permission enables you to specify whether requests can be made to

the generate events) resource, as well as blacklisting or whitelisting handler IDs. If handler IDs are blacklisted, then only their use will be prohibited. If handler IDs are present in the white list, then only their use will be allowed. When using the “emit_events” permission, the user must not have the “creation” and “modification” rights to use the handler.

Authorization modules

Module .. attribute:: LunaAccountIdWhiteLists

storage with white lists for authorization with Luna-Account-Id header

luna_api.app.auth.white_resources_list.WhiteLists

storage with white lists for authorization with basic/bearer authorization header

class luna_api.app.auth.white_resources_list.LunaAccountIdWhiteLists

White lists for authorization with Luna-Account-Id header .. warning:: Authorization with Luna-Account-Id header is deprecated

class luna_api.app.auth.white_resources_list.WhiteLists

White lists for authorization with basic/bearer authorization header

Authorization middleware

async luna_api.app.auth.auth_middleware.authMiddleware(request)

Authorization middleware, check a request account id

Parameters:

request – request

luna_api.app.auth.auth_middleware.checkCredentialsRights(verificationRequestKwargs, requestCredentials, request)

Verify request credentials rights :param verificationRequestKwargs: verification request kwargs (authorization data from headers) :param requestCredentials: credentials for request :param request: api request

Raises:

• VLException(Error.AccountTokenPermissionError, 403, False) if specified token supposed access to any data, but – account type is user (does not imply access to other accoounts data)

• VLException(Error.AccountQueryPermissionError, 403, False) if account type is user but specified query – parameter account_id (imply as data filter in other luna-* services) does not match the account id from authorization/Luna-Account-Id header

luna_api.app.auth.auth_middleware.checkVerificationKwargs(request, verificationRequestKwargs)

Check verification kwargs according due to request path, method and system configuration :param request: api request :param verificationRequestKwargs: verification kwargs

Raises:

• VLException(Error.BadHeaderAuth, 401, False) if no verification kwargs specified, service allows to use – Luna-Account-Id header and request required credentials

• VLException(Error.BadHeaderAuth, 401, False) if no verification kwargs specified, service not allows use – Luna-Account-Id header and request required credentialst

• VLException(Error.PermissionByTokenDenied, 403, False) if token kwargs specified, but request path and/or – method not allows access using token

• VLException(Error.AccountIdAuthDisabled, 403, False) if Luna-Account-Id header if specified, but service – not allows use Luna-Account-Id header

Return type:

None

luna_api.app.auth.auth_middleware.getAuthenticationHeader(sendBasicAuthInfo=True)

Get authentication header for 401 response :param sendBasicAuthInfo: whether to send basic auth info, otherwise bearer

Returns:

dict with WWW-Authenticate

Return type:

dict[str, str]

async luna_api.app.auth.auth_middleware.getRequestCredentials(verificationKwargs, request)

Verify and get request credentials :param verificationKwargs: keyword arguments for credentials verification request :param request: api request

Returns:

verified request credentials

Raises:

VLException(Error.CorruptedToken, 400, False) if failed to decode jwt token –

Return type:

RequestCredentials

luna_api.app.auth.auth_middleware.getVerificationRequestKwargs(request)

Get kwargs for credentials verification from request :param request: api request

Returns:

kwargs for credentials verification

Raises:

• VLException(Error.BadAccountId, 400, isCriticalError=False) if specified Luna-Account-Id header content – does not match expected

• VLException(Error.AccountIdAuthDisabled, 403, False) if Luna-Account-Id specified, but disabled by config –

Return type:

VerificationRequestKwargs

luna_api.app.auth.auth_middleware.logWhoIsRequestBelong(logger, verificationKwargs)

Log auth info who is request belong :param logger: logger :param verificationKwargs: verification kwargs

Return type:

None

luna_api.app.auth.auth_middleware.morphRequest(request, requestCredentials)

Morph request query/json/headers according to request method and request credentials :param request: api request :param requestCredentials: verified request credentials

Return type:

None

async luna_api.app.auth.auth_middleware.verifyCredentials(accountsClient, verificationKwargs)

Verify credentials :param accountsClient: account client :param verificationKwargs: authorization credentials

Returns:

dictionary with account-type and permissions (for token validation only)

Return type:

dict