Skip to main content

Register an External Application

Goal​

Register an external system (an integration, service, or middleware) so it can call Parsware APIs using its own credentials.

Prerequisites​

  • You are signed in to the Admin Control Center as a platform administrator.
  • You know which scopes the external system needs (for example, read access to app data).

Steps​

  1. Open the App Registrations page from the left navigation.
  2. Enter an application name that identifies the external system.
  3. Select the scopes the application needs from the list. Each scope grants a specific kind of access.
  4. Choose the security roles the application holds, if any. Leaving this empty is the least privilege: the application may call the platform and touch no record. A Custom API script runs as the application, under these roles — so an application whose scripts read or write records needs exactly the one role that may, and that role should be granted permissions only in the environments the application serves.
  5. Select Register app.
  6. A panel shows the new Client ID and Client secret. Copy the client secret now — it is shown only once and cannot be retrieved again.

What happens behind the scenes​

The external application becomes a registered API client. It authenticates with its client id and secret to obtain a short-lived access token, then calls Parsware APIs with that token. The token is limited to exactly the scopes you granted, names your tenant, and carries the roles you chose — which is what decides which records it may reach.

Troubleshooting​

  • "Scope … can only be granted by the platform operator." — parsware.provision and parsware.portals.serve belong to the operator's own servers (the website, the portal host) and are not in your list. No application of yours needs them.
  • A revoked application still answered for a while. Revoking stops it getting a new token at once, but a token it already holds is checked by each service on its own and keeps working until it expires, within the hour. To cut it off at once, remove its role's permissions in that environment as well: those are checked on every call.
  • "Scope … is not a known platform scope." — a requested scope is not in the catalog. Select scopes only from the list shown.
  • "Role … does not exist in this tenant." — a chosen role was deleted before the registration was saved. Reopen the panel and choose again.
  • "At least one scope must be granted." — select at least one scope before registering.
  • You lost the client secret — the secret cannot be recovered. Revoke the registration and register the application again to get a new secret.
  • Revoke an external application.