Docs menu
Integration accounts
The machine accounts your scripts and pipelines use, and what they can see.
In short
An integration account is a machine account that your scripts, data pipelines and integrations use to call Northstar. It has roles and teams like a person, and it only sees and changes what they allow. It signs in with API keys, never with a password.
What it is
People sign in to Northstar with their own account. Code should not: a person leaves, changes team or loses a right, and every pipeline that borrowed their account breaks or keeps rights it should not have.
An integration account solves this. It is created for one job, for example "dbt pipeline" or "CRM sync", and it:
- belongs to one organization;
- has a platform role, an organization role and teams, like any user;
- authenticates only with API keys;
- appears on the Developers page with its keys and when it was last used.
Create an account
Open Developers from your account menu, at the bottom of the sidebar, then click New developer account and fill in:
| Field | What to choose |
|---|---|
| Display name | The job it does, for example "Warehouse sync". It shows in the lists and logs. |
| Platform role | User in almost every case. See good practices. |
| Organization role | The features the integration calls, for example a role that can create KPIs and register dashboards. |
| Teams | The teams whose resources the integration works on. |
Then open the account and create an API key.
Creating accounts needs the developer account permissions of your organization role. Creating keys needs the permission to create and revoke API keys. By default, the Admin and Superadmin organization roles have both.
Roles and teams
An integration account follows the same access rules as a person:
- its organization role decides which features it can call: datasets, KPIs, dashboards, teams…;
- its teams decide which resources it can use. Each linked team adds the account as a team admin, with every right on that team's resources;
- its platform role should stay User. An Administrator account sees and can change everything on the platform.
You can change the roles and teams later, on the account's page. The change applies to the next call.
What it can see
- Reads return only what the account's teams can see, like the catalogue does for a person.
- Resources the integration creates follow the platform rules. A new dataset, for example, is only visible to platform administrators until a team gets access to it: assign it to a team right after creating it. See SDK recipes.
- The account belongs to the organization of its keys. To work in two organizations, create one account in each.
Good practices
- One account per integration. If a pipeline is compromised or retired, you revoke one account without touching the others.
- Least privilege. Give the organization role and the teams the integration needs, nothing more. Keep the platform role on User.
- Named for its job. The name shows in the keys list and the "last used" column: you should know at a glance what stopped calling.
- Review regularly. An account whose keys have not been used for months is probably no longer needed.
FAQ
Can I use my own account in a script? No. API keys exist only for integration accounts, and the SDK only authenticates with an API key.
Can someone sign in to the app with an integration account? No. It has no password: only its API keys authenticate it.
My script gets "forbidden" errors. Why? The account's organization role lacks the feature, or none of its teams has access to the resource. Check both on the account's page.