This article explains how the credentials, write scopes and catalogs of a registered application work, and which conditions must be met for the application to create, edit or delete campaigns and create contents through the SMARTFENSE API.
What is a registered application?
An application represents an external system that connects to the SMARTFENSE API. Each application has its own credentials and can only use the endpoints enabled by its scopes.
Applications are managed from Settings > Integrations > Registered applications.
For the full registration procedure, see the article Integración de APIs en SMARTFENSE.
Authentication
The SMARTFENSE API uses the OAuth 2.0 Client Credentials and Authorization Code flows to authenticate requests.
- Client Credentials: designed for server-to-server interactions. The application accesses the API without a user being present.
- Authorization Code: used when the application needs to access resources on behalf of a user. It requires that user's interaction and explicit consent through a browser.
For a request to be accepted:
- All requests must be authenticated.
- All requests must be made over HTTPS.
- Each request must include a bearer token in the
Authorizationheader.
Important: any call made over plain HTTP will fail.
Credentials
- Client ID and Client Secret: identify the application when it requests an access token.
- Client type: indicates where the credentials are stored.
- Confidential: the credentials are stored on a server.
- Public: the credentials are stored on the client side.
- Authorization grant type: defines the OAuth 2.0 flow the application uses to obtain its token.
- Client Credentials: for server-to-server integrations, with no user involved.
- Authorization Code: when a user must authorize the application from the browser. In this case, fill in the Redirect URIs.
Important: the Client Secret is only shown when the application is registered. Copy it and store it in a safe place, because it cannot be retrieved later.
Scopes
Scopes are the application's permissions. For security, select only those required for the endpoints you will use.
Campaign scopes
Create, edit and delete campaigns are three separate scopes. This makes it possible, for example, to allow an application to create campaigns without allowing it to delete them.
Only a user with permission to manage campaigns can:
- Grant those scopes.
- Modify or delete an application that already has them.
Scope to create contents
Only a user with permission to manage contents can:
- Grant the scope to create contents.
- Modify or delete an application that already has it.
On whose behalf does the application act?
Although no user is present at the time of the request with Client Credentials, write scopes are always linked to a person. The application uses them as long as that person remains active and keeps the corresponding permission:
| Authorization grant type | User the application acts on behalf of |
|---|---|
| Client Credentials | The user who registered the application. |
| Authorization Code | The user who authorized the application from the browser. |
Warning: if that user is deactivated or loses the permission to manage campaigns, the application can no longer create, edit or delete campaigns. The same applies to the scope to create contents if the user loses the permission to manage contents.
Catalogs
The application's catalogs define:
- Which content it can use in the campaigns it creates or edits, in the same way as an administrator user's catalogs.
- In which catalogs it can save the contents it creates.
When are they required?
Catalogs are required when the application has the scope to create or edit campaigns, or to create contents. They are not taken into account for any other scope.
Assignment options
- All catalogs: the application can use the content of all of the organization's catalogs.
- Selected catalogs: the application can only use the content of the catalogs you select.
In both cases, only the catalogs the organization has contracted count. If a catalog is no longer contracted, it stops applying without the need to edit the application.
Rules that limit catalogs
- You can only grant the catalogs assigned to the user who configures the application.
- The application only uses the catalogs assigned to the user it acts on behalf of: with Client Credentials, the user who registered it; with Authorization Code, the user who authorized it.
- If another administrator grants it a catalog that this user does not have, the application does not use it, even if it appears as granted.
- An application cannot edit a campaign whose content belongs to a catalog it does not have enabled.
Note: if an application cannot use a content or edit a campaign, first check the catalogs assigned to the user the application acts on behalf of, and then the catalogs granted to the application.
💡 Best practices
- Store the Client Secret in a secrets manager approved by your organization and never include it in code exposed on the client side.
- Use Client Credentials for automated processes with no user, and Authorization Code when each user must consent to access.
- Grant only the write scopes the integration needs. For example, avoid granting the scope to delete campaigns if the integration only creates them.
- For Client Credentials integrations, register the application with a stable user who is not going to lose their permission or be deactivated.
- Assign the application only the catalogs it will use, instead of All catalogs, when the integration works with a specific program.
- Before changing an administrator's permissions or catalogs, check whether any registered applications act on their behalf.
- Keep an internal record of which user registered or authorized each application and which scopes it has.