DataSimplePractical GuideLog inOpen DataSimple
DataSimple
Chapter 01Start here

Sign in and the workspace

Back to the index

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#

  1. 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: 1 or 01 is refused with Tenant ID must be exactly 3 digits, for example 001.
  2. After login you land in Notebooks. The left rail shows the objects your role may open, in four groups.
  3. The first user of a fresh installation is admin with 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:

Shell
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/*, except GET /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#

Next: 2. Connect source systems