CRUD user operations with the Astronomer API

2

This can be done by making POST requests to our Houston API with a service token in your authorization header. I’ve written an in-depth summary on how to accomplish the initial setup in this post, so I’ll spare the details here.

The only difference between that above use case (where I describe how to programmatically CRUD deployments via API requests) and this one is that we’ll be running mutations and queries to CRUD users instead of deployments. This will require some new GraphQL fragments, but the principles should be the same and you should be able to execute the request via any medium (javascript, python script, Postman, etc.).

Once you’ve followed the above guide to create a system-level service account and have the correct apiKey copied to your clipboard, you’ll be able to run any CRUD mutation on user objects that exist within your instance of the Astronomer platform.

Below, I’ll include the GraphQL fragment associated with creating, reading, updating (ie. changing roles), and deleting users against the Houston API.

Note: Postman has full support for GraphQL and is the recommended way to test your fragments.

Be sure to include your system-level API key as the Authentication header that is passed with your request and that you’re POSTing your request to houston.<YOUR-BASEDOMAIN>/v1*.

Programmatically Creating Users

Because of the way user creation works, it is much cleaner to invite users to the platform and let them sign in themselves than it is to create the user object directly against the database. Once a user is invited, they should receive an email prompting them to accept the invite and sign up using your configured authentication protocol.

GraphQL Fragment

We’ll return the user’s invite ID here, but note you can return any field associated with the user’s invite object.

mutation inviteUser {
  inviteUser(email:"<USER-EMAIL>")
  {
    id
  }
}

Once you run that request, the specified user will receive an invite to the platform in their email inbox.

Programmatically Reading Users

We can return a specific user’s information by running the users query against Houston.

GraphQL Fragment

query User {
  users(user: { email: "<USER-EMAIL>"} ){
    id
    username
    status
  }
}

Here, we’re returning that user’s userId, username (usually the same as their email), and status, but you can return anything that exists on the User type defined by Houston. Check out your GraphQL playground’s schema docs to peruse the possibilities.

Programmatically Deleting Users

We’ll do this via the removeUser mutation. This one is a bit trickier because we need to do it with the user’s userId- you’ll need to first read the user’s information to get their userId via the query fragment in the previous example.

GraphQL Fragment

mutation removeUser {
  removeUser(userUuid:"<USER-ID>")
  {
    id
  }
}

Programmatically Updating Users

Now, if you would like to change the roleBinding that a user has on a specific workspace, you can user the workspaceUpdateUserRole mutation. Note that user objects can have multiple role bindings, since users can be members of multiple workspaces and can even have a separate system-level role binding that allows them to access features reserved for system administrators.

In order to run this mutation, you’ll need the target workspaceId. You can either get that ID by querying for it against Houston or just viewing the string in your browser URL when you access your workspace.

GraphQL Fragment

Below, we’ll change the user’s role to WORKSPACE_EDITOR, but you should be able to make that user a WORKSPACE_ADMIN or WORKSPACE_VIEWER as well.

mutation workspaceUpdateUserRole{
  workspaceUpdateUserRole(
    workspaceUuid:"<WORKSPACE-ID>"
    email:"USER-EMAIL>"
    role: WORKSPACE_EDITOR
  )
}

Hope this helps!