API Services and Authorization
API services expose saved Data Connect datasets through authenticated HTTP requests. Open Data Connect → API calls to manage services, API roles, keys, documentation, and call logs.
Create A Service
- Create an API service and select its data source.
- Enter a name, stable service code, and optional description.
- Enable the service and save.
- Check the resource list for saved datasets from that source.
A source can have one API service. The service code forms part of the URL and cannot be changed after creation. Creating a service does not automatically create roles or issue keys.
Create A Role And Bind Datasets
- In API roles, create a role.
- Enter its name and optional description.
- Select one or more datasets from the paginated list.
- Configure each selected dataset's Fields, Scope, and Write permissions as needed.
- Save.
A newly selected dataset defaults to all available fields with query-only access. Inserts, updates, and deletes require separate grants. One role can bind several datasets, and several roles can bind the same dataset with different permissions. An empty role grants no dataset access.
API roles are independent of internal member roles. API clients use their bound API role rather than inheriting the permissions of a logged-in member.
Issue And Maintain API Keys
Create an API key and choose one role in the service. Configure its name, enabled status, optional expiry, and rate limit.
The complete secret is shown only when created or rotated. Copy it to the calling application's protected configuration. Later key lists show its prefix rather than the complete secret.
Send it in the X-API-Key request header. Rotating invalidates the previous secret. Disabling a key, role, or service prevents further use. A role in use by a key cannot be deleted until the keys are reassigned or removed.
Field And Row Permissions
Select the readable fields and configure a fixed data range per dataset. Client filters are applied together with that range and cannot broaden it. Member/department variables are unavailable for application-only API access.
Document fields such as a customer address appear as one field in the field-permission dialog. API metadata and field selectors can still expose configured JSON/XML subfields. Granting only a subfield does not grant its entire parent document or its siblings.
Dataset Changes And Authorization
The API uses the latest saved dataset; saving takes effect without a separate check-and-publish step.
| Saved dataset change | Role binding behavior |
|---|---|
| Name, description, field display name, or field order | Keeps existing authorization |
| New field | Adds read permission; does not add write permission |
| Deleted field | Removes its read/write/insert grants and related row-scope conditions; other fields remain usable |
| Same field, different type, expression, script source, or value source | Keeps its authorization |
| Main source, joined source, join type, or join conditions | Resets the affected binding to all available fields, query-only access, and no fixed row filter |
| Deleted dataset | Removes that dataset binding from every affected API role |
When a removed field was used in a nested row filter, its conditions and empty groups are removed. If no conditions remain, that binding has no fixed row restriction. Review the resulting access scope after such changes.
Authorization remaining valid does not guarantee that a caller's previous filter values or response parser remain compatible with a changed field type. Update the calling application when its data contract changes.
Write Permissions
Writes are available only for eligible datasets based on one physical database table with a usable primary key. Form models, views, and joined datasets are not writable through these API operations.
Grant methods and fields explicitly. The database account must also have the operation's privileges. All required primary-key fields must be readable.
- POST /records inserts one record and returns its key. Supply mandatory values; database-generated fields need not be submitted.
- PATCH updates selected granted fields by the complete primary key.
- PUT requires all writable fields granted to the role. It does not replace ungranted columns or primary keys.
- DELETE deletes one record identified by its complete primary key.
The fixed row scope is enforced for writes, and updates/inserts must also satisfy it after the change. No batch write is provided. Tests that execute writes change the actual source database.
Documentation And Testing
Open Documentation and testing, select a role and dataset, and select a valid API key for testing. Configure filtering, sorting, row limit, and whether field metadata should be returned.
The document shows method-specific requests, authorization requirements, examples, and responses. Use its copy/test controls, or download the generated Word document. The HTTP request reference explains common parameters and nested response paths.
Call Logs And Original Errors
Open Call logs and filter by keyword, HTTP status, or time. View a log's details to see the API key name, dataset, result, row count, elapsed time, error code, and original error chain.
Request details also show the HTTP method, Runtime-resolved URL, request ID, connection IP, and reported forwarding, Host, User-Agent and content headers. The connection IP is the socket peer; forwarding headers are reported values rather than verified client identity. Keyword search also matches method, URL, request ID and connection IP. Credentials and sensitive query values are redacted; request bodies are not recorded.
These logs also appear in System logs → Data Connect API and Data Cleanup → Logs. Cleanup uses creation time and retains services, roles, keys, grants and datasets.
The error-code display replaces underscores with spaces and uses lowercase. For example, DATA_CONNECT_API_STRUCTURE_CHANGED appears as data connect api structure changed. The machine-readable error response keeps its original code.
Original errors can identify the underlying database or rule-validation problem. Error details exclude SQL/row dumps and redact recognized credentials. Older logs created before error-detail recording may have no original error. Authenticated calls are logged; authentication failures before a principal is established are not included in this call-log list. Logs are retained for 30 days.