Skip to main content

Automate workspace management

Use the management API from your server, a CLI, or an automation job. Start with a successful workspace read. Add only the scopes needed by the operations below.

These commands create dashboard resources and print their results in a terminal. They do not build an app or display a login page. You can create the same kinds of resources through dashboard setup; choose this page when you want to test or automate the API. A scope is a permission attached to your developer token.

Replace the YOUR_... placeholders directly with your values, keeping the surrounding quotes. No environment setup is required. Windows examples use Command Prompt (CMD). Run the sections in order when creating resources; later requests use IDs returned by earlier ones.

Before you start​

The token from the first-API-call guide only has read_workspaces. Create a developer access token in Settings → General → Developer Access Tokens with the scopes for the sections you will run:

SectionRequired scopeDashboard label
Find an existing workspaceread_workspacesRead workspace data
Create a workspacewrite_workspacesManage workspaces
Read your active planread_plansRead plan and entitlement data
Create an OAuth clientwrite_clientsManage OAuth clients
Create a verification templatewrite_templatesManage email templates
Create a test userwrite_usersManage end-users

Use the new token's full value for every YOUR_DEVELOPER_TOKEN below. Keep the workspace ID, user-plan ID and OAuth client ID as you obtain them. Choose a real email address you control and a new password before creating the test user; [email protected] cannot receive email.

If you completed dashboard setup, reuse the workspace, client or template you already created and skip those creation requests. Obtain the existing workspace's id from the workspace list and the application's client_id from its details. You only need the plan lookup below if you are creating a client.

Use Terminal on macOS/Linux or Command Prompt on Windows. For each section, replace placeholders, run the whole command from your system's tab, then check the status and body before continuing. HTTP 201 means the resource was created; HTTP 200 means a read succeeded. A failed command does not provide a usable new ID. Keep a record of the IDs from successful responses so later requests use the same workspace and client.

Create a workspace​

Required scope: write_workspaces.

curl -i "https://api.syauth.com/e/v1/developer/workspaces/" \
  -H "X-Developer-Token: YOUR_DEVELOPER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example application"}'

Expect 201 with the workspace object. Use the returned id wherever YOUR_WORKSPACE_ID appears below.

You can confirm creation by opening Workspaces and finding the name you sent. If you lose the response, use the workspace-list request to find its ID instead of submitting another create request.

Read your active plan identifier​

Required scope: read_plans.

curl -i "https://api.syauth.com/e/v1/developer/plans/" \
  -H "X-Developer-Token: YOUR_DEVELOPER_TOKEN"

The response is an array. Replace YOUR_USER_PLAN_ID below with the relevant entry's id. This is your user-plan identifier, not a catalogue product ID. If no active plan is returned, resolve account activation in dashboard Billing.

Create an OAuth client​

Required scope: write_clients.

Replace YOUR_WORKSPACE_ID with the workspace's id, YOUR_USER_PLAN_ID with the active plan entry's id, and YOUR_REDIRECT_URI with the callback URL your app handles, for example http://127.0.0.1:8080/callback. Send the URI as an ordinary JSON string here; URL-encoding is only needed when placing it inside an authorization URL.

curl -i "https://api.syauth.com/e/v1/developer/clients/?user_plan_id=YOUR_USER_PLAN_ID" \
  -H "X-Developer-Token: YOUR_DEVELOPER_TOKEN" \
  -H 'Content-Type: application/json' --data-raw '{"name":"Example web app","workspace":"YOUR_WORKSPACE_ID","client_type":"public","redirect_uris":["YOUR_REDIRECT_URI"],"allowed_grant_types":["authorization_code","refresh_token"],"allowed_response_types":["code"],"allowed_scopes":["openid","profile","email"]}'

Expect 201. Save id for management calls and client_id for login. Use a confidential client only when its secret can remain on your server.

For testing without an app, register http://127.0.0.1:8080/callback and later run the manual callback receiver. Creating this client does not start that receiver. Reopen the client in Applications to check the stored settings.

Create a verification template​

Required scope: write_templates. Create this before the first test user if the workspace does not already have it.

Use the same YOUR_WORKSPACE_ID in the query string and the JSON body. Keep {{ verification_code }} and {{ timeout }} exactly as written: SyAuth fills them when sending email.

curl -i "https://api.syauth.com/e/v1/developer/templates/?workspace_id=YOUR_WORKSPACE_ID" \
  -H "X-Developer-Token: YOUR_DEVELOPER_TOKEN" \
  -H 'Content-Type: application/json' --data-raw '{"workspace":"YOUR_WORKSPACE_ID","name":"email_verification","subject":"Verify your email","body":"Your verification code is {{ verification_code }}. It expires in {{ timeout }} minutes."}'

Expect 201. If a template with that name already exists, review/update it using its ID instead of creating a duplicate.

Check the selected workspace's Email templates list for email_verification. This step saves the message format; it sends no email by itself.

Create a test user​

Required scope: write_users. Replace the email with an address you control so you can receive the verification code.

Use the same YOUR_WORKSPACE_ID in both places and the application's public client_id as YOUR_PUBLIC_CLIENT_ID. Replace the example password in both password and confirm_password with the same new value. Use at least 12 characters, including uppercase, lowercase, a number and a special character; handle any additional validation errors returned by the service.

curl -i "https://api.syauth.com/e/v1/developer/users/?workspace_id=YOUR_WORKSPACE_ID" \
  -H "X-Developer-Token: YOUR_DEVELOPER_TOKEN" \
  -H 'Content-Type: application/json' --data-raw '{"workspace":"YOUR_WORKSPACE_ID","oauth_client":"YOUR_PUBLIC_CLIENT_ID","email":"[email protected]","password":"ExamplePass!7264X","confirm_password":"ExamplePass!7264X","first_name":"Alex","last_name":"Developer","send_verification":true}'

Expect 201 with a user object. Continue at step 2: verify the email, then log in with that user's email/password and the same OAuth client. Do not run signup again for the user you just created. This is an administrative operation: your application's unauthenticated users must not receive your developer token.

You have completed the resource-creation walkthrough when the intended workspace, client, template and test user exist. Login is a separate test: use the email/password steps linked above or the hosted-login manual test. If verification mail does not arrive, use email troubleshooting before creating another user.

If a request returns 403, check its required scope against the token you actually sent, then check workspace access and plan limits. A token that can list workspaces may still be unable to create clients or users.

Read workspace, client, and user contracts for update/delete rules and ownership checks.