POST /config/access/authorized_services

Edit online

Creates an authorized service. The response to this API invocation will contain the API token. This will be the only time the token value is available.

Any user or authorized service can call this endpoint. To create an authorized service with any user role, security profile, or tenant, the caller must have the Administrator Manager permission. Callers who don't have the Administrator Manager permission can only create an authorized service with their own user role, security profile and tenant. An authorized service that is created by a caller who doesn't have the Administrator Manager permission expires no later than the default expiration time, even if the caller enters a later time. The default expiration time is also what is set as the expiration date for the authorized service if the expiration_date is not set in the request. This default expiration time can be configured using the Authentication Settings API found here: /api/system/authorization/settings.

Only the label, tenant_id, security_profile_id, user_role_id, and expiration_date fields can be set when creating an authorized service. All other fields are ignored.

Table 1. POST /config/access/authorized_services resource details
MIME Type
application/json

Table 2. POST /config/access/authorized_services request parameter details
Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 3. POST /config/access/authorized_services request body details
Parameter	Data Type	MIME Type	Description	Sample
authorized_service	Object	application/json	Only the label, tenant_id, security_profile_id, user_role_id, and expiration_date fields can be set when creating an authorized service. All other fields are ignored.	{ "created_by": "String", "creation_date": 42, "expiration_date": 42, "id": 42, "label": "String", "last_used_date": 42, "security_profile_id": 42, "tenant_id": 42, "token": "String", "user_role_id": 42 }

Table 4. POST /config/access/authorized_services response codes
HTTP Response Code	Unique Code	Description
201		response with the new authorized service structure. Location header set to the URL of the new authorized service.
422	95103001	The label field must be provided.
422	95103002	The security_profile_id field must be provided.
422	95103003	The security_profile_id provided must reference a deployed security profile.
422	95103004	The user_role_id field must be provided.
422	95103005	The user_role_id provided must reference a deployed user role.
422	95103006	The tenant_id provided must reference an existing tenant.
422	95103007	The tenant_id was provided, but the security_profile_id does not limit access to data in that tenant.
422	95103008	The authorized service label must be unique for all authorized services and usernames.
422	95103009	security_profile_id must be set to the Admin security profile when creating an authorized service with the System Administrator permission.
422	95103010	tenant_id must be null when creating an authorized service with a user role that contains the System Administrator permission.
422	95103011	The length of the label field cannot exceed 255 characters.
422	95103012	The expiration_date must expire before the default expiration time if you do not have the Administrator Manager permission.
422	95103013	The expiration_date must be set to a time in the future.
422	95103014	The limit for the number of authorized services that a user or authorized service without the Administrator Manager permission is allowed to create has been met by the caller.
422	95103015	The user_role_id must match your own if you do not have the Administrator Manager permission.
422	95103016	The security_profile_id must match your own if you do not have the Administrator Manager permission.
422	95103017	The tenant_id must match your own if you do not have the Administrator Manager permission.
422	95103018	Manage Local Only Authentication Setting permission required to perform action.

Response Description

label - String - The label of the authorized service. Authorized service labels and usernames must be unique between them. This field is not configurable if the caller does not have the Administrator Manager permission. The label will instead be auto-generated by appending the callers label with a randomly generated UUID.
token - String - The token of this authorized service. The authorized service token is a pre-authorized key. This token can be used in place of a username and password when authentication to the APIs. This field is only available in the response to a POST to the /api/config/access/authorized_services endpoint.
tenant_id - Long - (Optional) The tenant ID of the authorized service. Access a list of tenants using /api/config/access/tenant_management/tenants. When set, this field will restrict the security_profile_id field to ones that are completely contained within the specified tenant. Only callers with the Administrator Manager permission can configure this field. For callers without the Administrator Manager permission, the tenant_id of the authorized service must be the same as the tenant_id of the caller.
security_profile_id - Long - The security profile ID of the authorized service. Access security profiles using /api/config/security_profiles API. Only callers with the Administrator Manager permission can configure this field. For callers without the Administrator Manager permission, the security_profile_id of the authorized service must be the same as the security_profile_id of the caller.
user_role_id - Long - The user role ID of the authorized service. Access user roles using /api/config/user_roles API. Only callers with the Administrator Manager permission can configure this field. For callers without the Administrator Manager permission, the user_role_id of the authorized service must be the same as the user_role_id of the caller.
expiration_date - Long - The time in milliseconds since epoch that this authorized service will expire. This field, if set, must always be set to a time in the future. Only callers with the Administrator Manager permission can set this field to null. If this field is set to null, this authorized service does not expire. A caller who does not have the Administrator Manager permission can only set the expiration_date to a value that is less than or equal to the default expiration time described in the main description of this endpoint, and cannot set it to null. If this field is not set, the expiration_date is set to the default expiration time. This value will be truncated to seconds.

Response Sample


{
    "created_by": "String",
    "creation_date": 42,
    "expiration_date": 42,
    "id": 42,
    "label": "String",
    "last_used_date": 42,
    "security_profile_id": 42,
    "tenant_id": 42,
    "token": "String",
    "user_role_id": 42
}