How it works#
You sign in with a user name, a password and a tenant id. The tenant is a three-digit number (000 to 999); every table, grant, filter, run and audit line you will see belongs to that tenant only, and a second tenant on the same server sees none of it. Your role decides which tabs of the left rail you see; the same table of role and tab is enforced on the server, so an API behind a tab your role lacks answers 403 No access to <tab> (ask an administrator). A user has one active browser session: signing in again from another browser or device closes the older session for that user and tenant (sign-ins from the command-line tool are left alone).
Steps#
- Open the application URL. The login page has three fields: Username, Password, Tenant ID. The tenant defaults to
001. It must be exactly three digits:1or01is refused with Tenant ID must be exactly 3 digits, for example 001. - After login you land in Notebooks. The left rail shows the objects your role may open, in four groups.
- The first user of a fresh installation is
adminwith the first-boot seed password set by the installation; the administrator changes it at the first login (Administration → Users → Reset password).
Roles#
| Role level | Who | What they can do beyond their tabs |
|---|---|---|
| Administrator roles: Admin, Super Admin, Super Master, System Administrator, Chief Agent, or any role with level 100 or more | the platform team | see every tab unless an explicit tab list was saved for the role; create users and roles; all governance actions (grants, revokes, row filters, column masks, schema and table deletes, bootstrap); issue Data Quality certificates; tenant-wide History |
Other roles (for example a role you name Data Engineer or Analyst) |
everyone else | exactly the tabs enabled under Administration → Roles → Screens; governance actions only on tables where they hold MANAGE |
| governance roles (named by your administrator) | data stewards, compliance | may issue Data Quality certificates in addition to their tabs |
An administrator grants tabs under Administration → Roles → the role → Screens (or PUT /api/admin/roles/:id/tabs with { "tabs": { "databridge": true } }). A change applies to the next request on that server process and within 30 seconds elsewhere. The first explicit tab row saved for an administrator role turns "all tabs" into "only the listed tabs", so grant the full set for such a role.
The left rail#
| Group | Object | What you do there | Chapter |
|---|---|---|---|
| Ingestion | Data Source | save connections to databases, APIs, Kafka clusters and storage targets; each gets a DS-<n> number |
2 |
| Ingestion | Databridge | copy tables, files, backups or topics into the lake and keep them current | 4 |
| Ingestion | Bronze CDC | merge the latest loads into one row per key in bronze |
5 |
| Ingestion | Workflow | build a source → bronze → silver → gold flow by chatting with Sarah | 8 |
| Ingestion | ELS_DB | read-only browser of the application's own database (for developers) | 12 |
| Lakehouse & Storage | Lakehouse | the Unity Catalog tree: datasimple → layer → format folder → table; preview, history, permissions, lineage |
9 |
| Lakehouse & Storage | Data Lake | raw storage browser (buckets, uploaded files, Delta folders by path) | 3 |
| Lakehouse & Storage | Semantics | business terms and runnable metrics | 9 |
| Lakehouse & Storage | Data Quality | profiles, rules, quarantine, freshness, certificates | 9 |
| Lakehouse & Storage | DataShare | share tables outside over Delta Sharing | 9 |
| Workflows & Pipelines | Notebooks | SQL, Python, Markdown, Chart and Params cells on a Spark kernel | 7 |
| Workflows & Pipelines | Schedules | run one notebook on a cron, with retries and notifications | 7 |
| Workflows & Pipelines | Pipelines | a graph of notebook, dbt, Flink SQL and Workflow steps | 8 |
| Workflows & Pipelines | Dataflow | the orchestration view, when the Dataflow scheduler service is configured | 8 |
| Workflows & Pipelines | Deployment | compare and promote notebooks, pipelines, schedules and Data Sources to the next environment | 12 |
| Monitoring & Admin | History | every action in the workspace, including DataBridge loads | 11 |
| Monitoring & Admin | Log | one line per cell run and per DataBridge job, with rows, duration and error text | 11 |
| Monitoring & Admin | Lineage | table and column lineage, impact mode | 9, 11 |
| Monitoring & Admin | Sarah | ask for a report in plain words; a Gold-only dashboard with the SQL behind it | 14 |
| Monitoring & Admin | Agent | ask in plain words; writes wait for approval | 9 |
| Monitoring & Admin | Settings | your notebook defaults, the Unity Catalog status card and your personal API tokens | 9 |
| Monitoring & Admin | Administration | users, roles, tab access, governance console, Ingestion Jobs, activity and error logs | 1, 11 |
Tab keys, as the API and the role editor name them: notebooks, pipelines, deploy, jobs, airflow, files, catalog, semantics, dataquality, sharing, workflow, databridge, data, bronze, elsdev, agent, lineage, activity, log, settings, admin.
Scripting against the application#
Every API in this guide accepts either the session cookie of a signed-in user or a personal API token. Use a token for scripts and scheduled jobs: it does not expire with the browser session, and you can revoke it on its own.
Create a token. Open Settings → Personal API tokens, type a name (for example nightly export), choose an expiry (30 days, 90 days, 1 year or no expiry) and click Create token. The token, dsp_ followed by 43 characters, is shown once, with a Copy button. Copy it into your secret store now: the server keeps only a hash of it, so it cannot be shown again. If you lose it, revoke it and create a new one. The API equivalent, from a signed-in session, is POST /api/auth/tokens {"name":"nightly export","expiresInDays":90} (expiresInDays: 30, 90, 365 or null).
Use it. Send it in the Authorization header:
export DSP_TOKEN='dsp_...' # from Settings; keep it out of scripts and Git
curl -s -H "Authorization: Bearer $DSP_TOKEN" https://<your-app>/api/auth/me
curl -s -H "Authorization: Bearer $DSP_TOKEN" https://<your-app>/api/notebooks
The request runs as you: same tenant, same role, same tabs (403 No access to <tab> applies to scripts exactly as in the browser) and the same table permissions. No session cookie is created. A token stops working when it expires, when you revoke it, or when your account is locked. The answer is then 401 with code TOKEN_INVALID (or ACCOUNT_LOCKED). The list in Settings shows each token's name, its first characters (dsp_abcd…), when it was created, when it expires and when it was last used (updated at most once a minute).
Revoke it. Click Revoke next to the token in Settings (or DELETE /api/auth/tokens/<id> from a signed-in session). Scripts using it are refused from the next request. Creating and revoking a token is recorded in History (auth.api_token_create, auth.api_token_revoke), and every audited action a token makes is marked with the token's id.
What a token cannot do. These need you signed in to the application, and a token request gets 403 with code TOKEN_NOT_ALLOWED:
- create or revoke tokens (a token may list your tokens with
GET /api/auth/tokens); - sign in, sign out or reset a password (
/api/auth/*, exceptGET /api/auth/me); - administer users, roles and role tab access (
/api/admin/users…,/api/admin/roles…), even for an administrator; - create or revoke other credentials: Delta Sharing recipients and dbt client keys.
Tokens are never written to a log; any dsp_… text in a log line is shown as dsp_[redacted].
You can still script with the session cookie: log in once with POST /api/auth/login {"username","password","tenantid"} and reuse the cookie jar. The same tab rules apply.
Read more#
- Roles and tab enforcement in detail: Tab permissions.
- Unity Catalog OSS, the open project whose model (catalog, schema, table, privileges) DataSimple follows: https://docs.unitycatalog.io/