Run your first sync
You will have a running instance and a successful REST query.
You decide: Choose a small source area for your first sync.
Time: Setup requires database and directory access. Initial sync time depends on directory size and load.
Next: Choose an API
Use this walkthrough on a trusted evaluation network. Download credentials, a database and LDAP access must be ready before you begin.
Prerequisites
Section titled “Prerequisites”- PostgreSQL database (17+, recommended 18+)
- Access to an LDAP directory (Active Directory, OpenLDAP, etc.)
- curl or any HTTP client
Step 1: Download
Section titled “Step 1: Download”Step 2: Configure
Section titled “Step 2: Configure”We need a config file that points at our database and LDAP source. Create identity-scribe.conf:
# Where to store synced datadatabase.url = "jdbc:postgresql://localhost:5432/scribe"database.user = "scribe"database.password = ${DB_PASSWORD}
# LDAP source to sync fromldap.url = "ldap://your-ldap-server:389"ldap.bind-dn = "cn=reader,dc=example,dc=com"ldap.bind-password = ${LDAP_BIND_PASSWORD}
# What to sync -- one transcribe per entry type# The key ("users" here) becomes the entry type we query againsttranscribes { users { ldap { base = "ou=users,dc=example,dc=com" filter = "(objectClass=person)" scope = sub attributes = "cn, sn, givenName, mail, telephoneNumber" } }}
# Serve REST for the first querychannels.rest.enabled = trueEach transcribe defines an entry type; its ldap block sets the source base DN, filter, scope, and the attributes to capture. Secrets use ${ENV_VAR} substitution so they stay out of config files. For relationship fields such as groups, roles, managers, or owners, see Attribute Modeling before deciding which side to store.
REST is off by default, so this configuration enables it. After the first query, choose another API if your client needs one.
Step 3: Run
Section titled “Step 3: Run”export DB_PASSWORD="your-db-password"export LDAP_BIND_PASSWORD="your-ldap-password"./identity-scribe-* --mode dev./identity-scribe-* --mode devWe should see a startup banner with the version and configured channels. Once it’s ready, we verify:
curl http://localhost:8080/readyzExpected output: ok. On this first start, /readyz answers 503 until the initial sync has finished, so retry until it reports ok. Index builds may still be running; use /observe/convergence when you need to wait for everything to finish.
If the binary fails with Illegal instruction or similar on startup, see CPU Compatibility.
Step 4: Query via REST
Section titled “Step 4: Query via REST”set -o pipefail
# List all userscurl -fsS http://localhost:8080/api/entries/users | jq
# Search by name (FleX filter syntax -- human-readable shorthand)curl -fsS -G http://localhost:8080/api/entries/users --data-urlencode "filter=cn ^= John" | jq
# Get a specific entry (use an entryID from the list response above)curl -fsS http://localhost:8080/api/entries/users/ENTRY-ID-HERE | jqWe should see a JSON response with an edges array. Each entry includes its entryID, cn, mail, and the other attributes we configured in the transcribe.
Scribe auto-detects the filter format, so we can also use LDAP syntax (cn=John*), JSON {"cn":{"sw":"John"}}, or SCIM cn sw "John". FleX is the human-readable shorthand format. See Choosing Filters for trade-offs between formats.
Optional: query through GraphQL or LDAP
Enable GraphQL with channels.graphql.enabled = true, then restart Scribe.
set -o pipefailcurl -fsS -X POST http://localhost:8080/graphql \ -H "Content-Type: application/json" \ -d '{"query": "{ users(filter: \"cn ^= John\") { edges { node { cn mail } } } }"}' | jqThe response wraps results in data.users.edges. Each node contains the fields we asked for — cn and mail in this case.
The GraphQL schema is generated from our transcribe configuration. Open http://localhost:8080/graphql in a browser to explore it interactively with the built-in GraphiQL IDE.
Query via LDAP
Section titled “Query via LDAP”Configure channels.ldap.listen = [{ port = 10389 }], then restart Scribe. These examples require ldapsearch; replace the base with the area you configured.
# List all entriesldapsearch -H ldap://localhost:10389 -x -b "o=data" "(objectClass=*)" cn
# Search users by nameldapsearch -H ldap://localhost:10389 -x -b "ou=users,o=data" "(cn=John*)" cn mailThe LDAP channel prints entries in LDIF format — one attribute per line, entries separated by blank lines. We should see the same data we queried via REST and GraphQL.
Optional: explore the UI
Section titled “Optional: explore the UI”What’s next
Section titled “What’s next”| Goal | Page |
|---|---|
| Understand the data flow | Architecture |
| Learn how sync works | Change Detection |
| Tune your config | Configuration |
| Add auth and TLS | Production Checklist |
| Set up monitoring | Monitoring |
| Fix issues | Troubleshooting |
| Browse all config keys | Reference |