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/accounts	get	account - view
/6/account	get	account - view
/6/tokens	post	token - creation
	get	token - view
/6/tokens/{token_id}	put	token - modification
	get	token - view
	delete	token - deletion
/6/sdk	post	resources - sdk
/6/iso	post	resources - iso
/6/samples/faces	post	face_sample - creation
/6/detector	post	face_sample - creation
/6/samples/faces/{sample_id}	get	face_sample - view
	head	face_sample - view
	delete	face_sample - deletion
/6/samples/bodies	post	body_sample - creation
/6/samples/bodies/{sample_id}	get	body_sample - view
	head	body_sample - view
	delete	body_sample - deletion
/5/samples/{sample_id}	get	face_sample - view
	head	face_sample - view
	delete	face_sample - deletion
/6/samples/{sample_id}	get	face_sample - view
	head	face_sample - view
	delete	face_sample - deletion
/6/extractor	post	attribute - 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 - modification
	get	face - view
	delete	face - deletion
/6/faces/{face_id}/attributes/samples	get	face_sample - 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/general/events/statistic	post	event - view
/6/general/events	get	event - view
/6/general/events/{event_id}	get	event - view
	head	event - view
/6/ws	get	event - view
/6/general/ws	get	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}/notification_policy	get	task - view
	put	task - modification
/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/tasks/schedules	post	task - creation
	get	task - view
/6/tasks/schedules/{schedule_id}	get	task - view
	put	task - modification
	patch	task - modification
	delete	task - deletion
/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/verifiers/{verifier_id}/raw	post	verifier - verify *6
/6/verifiers/{verifier_id}/verifications	post	verifier - verify *6
/6/liveness	post	resources - 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
/6/lambdas	post	lambdas - creation
	get	lambdas - view
/6/lambdas/{lambda_id}	put	lambdas - modification
	get	lambdas - view
	patch	lambdas - modification
	head	lambdas - view
	delete	lambdas - deletion
/6/lambdas/{lambda_id}/update	post	lambdas - creation
/6/lambdas/{lambda_id}/status	get	lambdas - view
/6/lambdas/{lambda_id}/logs	get	lambdas - view
/6/lambdas/{lambda_id}/image/status	get	lambdas - view
/6/lambdas/{lambda_id}/image/logs	get	lambdas - view
/6/lambdas/{lambda_id}/proxy	post	lambdas - view
/6/streams	post	video_stream - creation
	get	video_stream - view
	delete	video_stream - deletion
/6/streams/count	get	video_stream - view
/6/streams/{stream_id}	put	video_stream - modification
	get	video_stream - view
	patch	video_stream - modification
	head	video_stream - view
	delete	video_stream - deletion
/6/streams/{stream_id}/ws	get	video_stream - view
/6/groups	post	video_group - creation
	get	video_group - view
/6/groups/count	get	video_group - view
/6/groups/{group_id}	get	video_group - view
	patch	video_group - modification
	delete	video_group - deletion
/6/groups/count	get	video_group - view
/6/linker	patch	video_group - modification
/6/analytics	get	video_analytic - view
/6/analytics/{analytic_id}	get	video_analytic - view
/6/analytics/{analytic_id}/docs	get	video_analytic - view

*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.

*6 - The “verify” permission enables you to specify whether requests can be made to

raw verification and perform verification resources, as well as blacklisting or whitelisting verifier IDs. If verifier IDs are blacklisted, then only their use will be prohibited. If verifier IDs are present in the white list, then only their use will be allowed.

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.AuthIgnoreList

White lists for ui authorization

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)

Return type:

None

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

luna_api.app.auth.auth_middleware.getAuthenticationHeader(sendBasicAuthInfo=True, setCookieHeader=False)

Return type:

dict[str, str]

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

Returns:

dict with headers

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

Return type:

RequestCredentials

Verify and get request credentials :param verificationKwargs: keyword arguments for credentials verification request :param request: api request :param ignoreAuthError: whether to ignore authorization credentials verification error

Returns:

verified request credentials

Raises:

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

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

Return type:

VerificationRequestKwargs

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 –

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

Ignore auth error

Return type:

bool

Parameters:

request – request

Returns:

ignoreAuthError flag

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

Return type:

None

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

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

Return type:

None

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

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

Return type:

dict

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

Returns:

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