Attribute connectors

Use these endpoints to manage the attribute connectors of a project.

All requests require the X-Project-Id header. Read access requires the Project viewer role and changes require the Project editor role. Read Permissions for details.

note

My workspace stages POST, PATCH, and DELETE requests, which return 202. They are validated and applied when the workspace is promoted.

Endpoints

Method	Path	Description
GET	/api/attribute-connectors	List the attribute connectors.
GET	/api/attribute-connectors/by-attributes	List the attribute connectors that use specific attributes.
GET	/api/attribute-connectors/{fqn}	Get an active attribute connector by fully qualified name.
GET	/api/attribute-connectors/id/{uid}	Get an attribute connector version by ID, including older versions.
POST	/api/attribute-connectors	Create an attribute connector.
PATCH	/api/attribute-connectors/{fqn}	Update an attribute connector.
DELETE	/api/attribute-connectors/{fqn}	Delete an attribute connector.
GET	/api/attribute-connectors/export	Export the attribute connectors as a JSON file.
POST	/api/attribute-connectors/import	Import attribute connectors from a JSON file.

List and read

• GET /api/attribute-connectors returns an array. You can narrow it with the optional query parameters namespace and typeName (for example, sql), which must match exactly.
• GET /api/attribute-connectors/by-attributes requires the attributeIds query parameter, with one or more attribute IDs. Repeat the parameter or separate the IDs with commas. It returns the attribute connectors that provide, or use as a key, any of those attributes.

The fully qualified name (FQN) of an attribute connector is <namespace>.<name>.

Create an attribute connector

curl -X POST "https://<authorization-hub-url>/api/attribute-connectors" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Project-Id: <project-id>" \
  -H "Content-Type: application/json" \
  -d @attribute-connector.json

{
  "namespace": "hr",
  "name": "employee_directory",
  "type": "ldap",
  "description": "Employee attributes from the corporate directory",
  "configuration": {
    "connection": { },
    "mappings": [ { "attributeName": "user.department" }, { "attributeName": "user.name" } ]
  },
  "attributes": {
    "user.department": "0f7b5bd2-9d5f-45f0-a9b9-8c8d0f4a6a11",
    "user.name": "8a1d4f7c-3b2e-4c9a-b6d5-7e0f1a2b3c4d"
  }
}

The configuration above is abbreviated. Its full structure depends on the attribute connector type.

Field	Required	Description
namespace	Yes	Up to 255 characters. Segments separated by single dots. Letters, digits, and underscores only, starting with a letter or underscore.
name	Yes	Up to 255 characters. Letters, digits, and underscores only, starting with a letter or underscore.
type	Yes	The attribute connector type. See Attribute connector types.
description	No	A description.
configuration	Yes	The type-specific connection and mapping configuration.
attributes	Yes	A map from the fully qualified name of every attribute that the configuration refers to, to that attribute's ID.
providedAttributes	No	A list of { "attributeName": "<fqn>" }. Each entry must correspond to an attribute provided by the configuration's mappings.

The namespace and name cannot be reserved words. For attribute connectors, the whole value is compared, ignoring case.

tip

The structure of configuration depends on the attribute connector type and mirrors the options in the attribute connector form. To get a working example, create an attribute connector in the interface, then read it with GET /api/attribute-connectors/{fqn} or export it.

Attribute connector types

type	Connector
table	Table
sql	SQL
ldap	LDAP
http	HTTP
json_parser	JSON parser
xml_parser	XML parser
jwt_parser	JWT parser

Configuration checks

Authorization Hub derives the provided attributes and the key attributes from the mappings of the configuration and checks them against the attributes map:

• Every mapping needs an attributeName, and every attribute it names, including key attributes, must be in attributes.
• An attribute cannot be its own key.
• table, sql, and ldap need at least one mapping.
• http needs an identifier, a connection, and mappings. If authentication is present, it cannot be empty. If a header in the connection has a headerKey, it must be an object that identifies the key attribute, with an attributeName that is a string, and not a plain string.
• json_parser, xml_parser, and jwt_parser need an identifier, a source, and mappings.

Other parts of the configuration are stored as provided.

Update an attribute connector

An update uses the application/merge-patch+json content type. Send only the fields to change. If you send a configuration, also send the attributes map. If you omit the configuration, the existing configuration is kept and the attributes are derived from it again.

An effective update creates a new version of the attribute connector with a new id and retires the previous one. Sending an update that changes nothing returns the existing attribute connector.

Delete an attribute connector

Deleting returns 204. The attribute connector is retired rather than removed, and its name can be reused.

Response

Field	Description
id	The ID of this version.
fqn, namespace, name, description, type	Identification.
configuration	The configuration.
attributes	The map from attribute FQN to attribute ID.
providedAttributes	The attributes the attribute connector provides, each with its keyAttributes.
className	The class that implements the attribute connector type, as used in domains.
createdAt, createdBy, updatedAt, updatedBy	Audit information.

Export and import

GET /api/attribute-connectors/export returns a JSON file with an array of all attribute connectors, with the name in the Content-Disposition header (attribute-connectors_<timestamp>.json). Each element has the id, fqn, namespace, name, description, type, configuration, attributes, and providedAttributes. The file does not include the attributes themselves.

POST /api/attribute-connectors/import takes a multipart/form-data request with the file in a part named file:

curl -X POST "https://<authorization-hub-url>/api/attribute-connectors/import" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Project-Id: <project-id>" \
  -F "file=@attribute-connectors.json;type=application/json"

• The file must be in the export format. Unknown properties are rejected, and so are empty (null) entries. The message names the position of the entry.
• Attributes are matched to the target project by fully qualified name. The IDs in the file are ignored. Import the attributes first. The import never creates attributes.
• Attribute connectors are matched by fully qualified name. A new one is created, and an existing one is replaced by the file's content.

The import returns 202 and stages the changes in your workspace. The body has the draftId, a summary (total, created, edited, and failed), the items that were staged, and the failures. An attribute connector that refers to attributes missing from the project is not staged and is listed in failures with the reason, while the others are staged.

Read Import and export for the behavior in the interface.

Errors

Status	errorCode	Cause
400	INVALID_REQUEST	A field is missing or invalid.
400	MISSING_FQNS, MISSING_ATTRIBUTE_NAME	The attributes map is missing an attribute that the configuration uses.
400	ATTRIBUTE_CANNOT_KEY_ITS_SELF	An attribute is defined as its own key.
400	INVALID_HEADER_KEY	The headerKey of an http connection header is not an object with an attributeName. The message names the header.
400	AC_DOES_NOT_HAVE_ATTRIBUTES, AC_DOES_NOT_HAVE_CONFIGURATION	An update has a configuration without attributes, or the attribute connector has no configuration.
400	AC_IMPORT_ATTRIBUTES_NOT_FOUND	An imported attribute connector refers to attributes that do not exist in the project. The message lists them.
400	AC_IMPORT_SCHEMA_INVALID	The imported file does not match the expected format.
404	FQN_DOES_NOT_EXIST, ID_DOES_NOT_EXIST, ATTRIBUTE_CONNECTOR_NOT_FOUND	The attribute connector does not exist.
404	NO_MAPPINGS_FOUND	A table, sql, or ldap configuration has no mappings.
404	AC_TYPE_DOES_NOT_EXIST	The type is not a supported attribute connector type.
409	DUPLICATE_ATTRIBUTE_CONNECTOR	An attribute connector with this fully qualified name already exists.
409	PROVIDED_ATTRIBUTE_NOT_EXIST_ON_MAPPING	A providedAttributes entry does not match a mapping in the configuration.