Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

POST /config/access/authorized_services

SUMMARY 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:

POST /config/access/authorized_services resource details

MIME Type

application/json

Table 2: POST /config/access/authorized_services request parameter details:

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:

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:

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.

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