GraphQL API

Authorizer instance supports GraphQL natively and thus helps you share the common schema for your frontend applications.

You can play with GraphQL API using the GraphQL playground that comes with your Authorizer instance. Access GraphQL playground on the instance same as of your Authorizer instance URL.

Note super admin only queries / mutations starts with underscore _.

Table of Contents

• GraphQL API
  • Queries
    • meta
    • session
    • profile
    • validate_jwt_token
    • validate_session
    • _users
    • _user
    • _verification_requests
    • _admin_session
    • _env
    • _webhook
    • _webhooks
    • _webhook_logs
    • _email_templates
  • Mutations
    • signup
    • login
    • magic_link_login
    • logout
    • update_profile
    • verify_email
    • resend_verify_email
    • forgot_password
    • reset_password
    • revoke
    • verify_otp
    • resend_otp
    • verify_totp
    • deactivate_account
    • _admin_signup
    • _admin_login
    • _admin_logout
    • _update_env
    • _update_user
    • _delete_user
    • _invite_members
    • _revoke_access
    • _enable_access
    • _generate_jwt_keys
    • _test_endpoint
    • _add_webhook
    • _update_webhook
    • _delete_webhook
    • _add_email_template
    • _update_email_template
    • _delete_email_template

Queries

meta

Query to get the meta information about your authorizer instance. eg, version, configurations, etc It returns Meta type with the following possible values

Sample Query

query {
  meta {
    version
    client_id
    is_google_login_enabled
    is_github_login_enabled
    is_facebook_login_enabled
    is_email_verification_enabled
    is_basic_authentication_enabled
    is_magic_link_login_enabled
    is_sign_up_enabled
  }
}

session

Query to get the session information.

Note: Session information should be present as HTTP Cookie. If the information is not present or an invalid data is present it throws unauthorized error

This query can take a optional input params of type SessionQueryInput which includes roles to verify if the current token is valid for a given roles.

Request Params

It returns AuthResponse type with the following keys.

Response

Sample Query

query {
  session(params: { roles: ["admin"] }) {
    message
    access_token
    expires_in
    user {
      id
      email
      roles
    }
  }
}

profile

Query to get the profile information of a user. It returns User type with the following keys.

Note: this is authorized route, so Authorization Header with bearer access token must be present or HTTPs cookie should be present.

Sample Query

query {
  profile {
    given_name
    family_name
    email
    picture
    roles
  }
}

validate_jwt_token

Query to validate the given jwt token. This query needs input params of type ValidateJWTTokenInput

Request Parameters

It returns ValidateJWTTokenResponse type with the following keys.

Response

Sample Query

query {
  validate_jwt_token(
    params: { token_type: "access_token", token: "some jwt token" }
  ) {
    is_valid
  }
}

validate_session

Query to validate the browser session. This query needs input params of type ValidateSessionInput

Request Parameters

It returns ValidateSessionResponse type with the following keys.

Response

Sample Query

query {
  validate_session(params: { cookie: "" }) {
    is_valid
  }
}

_user

Query to get a specific user by either id or email.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer.admin as http only cookie.

{
  "x-authorizer-admin-secret": "ADMIN_SECRET"
}

It requires either of following parameters

Request Param

Sample Query

query {
  _user(params: {
    id: '123-123123-1231231'
  }) {
    id
    email
  }
}

It returns the whole User object mentioned in profile query section

_users

Query to get all the _users. This query is only allowed for super admins. It returns array of users Users with below mentioned keys.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer.admin as http only cookie.

{
  "x-authorizer-admin-secret": "ADMIN_SECRET"
}

It can take optional params input of type PaginatedInput with following keys

Request Params

Sample Query

query {
  _users(params: {
    pagination: {
      page: 2
      limit: 10
    }
  }) {
    pagination: {
      offset
      total
      page
      limit
    }
    users {
      id
      given_name
      family_name
      email
      picture
      roles
    }
  }
}

_verification_requests

Query to get all the _verification_requests. This query is only allowed for super admins. It returns array of verification requests [VerificationRequest!]! with following keys.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

{
  "x-authorizer-admin-secret": "ADMIN_SECRET"
}

It can take optional params input of type PaginatedInput with following keys

Request Params

Sample Query

query {
  _verification_requests(params: { pagination: { limit: 10, page: 2 } }) {
    pagination {
      limit
      offset
      page
    }
    verification_requests {
      id
      token
      email
      expires
      identifier
    }
  }
}

_admin_session

Query to get admin session for dashboard

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

{
  "x-authorizer-admin-secret": "ADMIN_SECRET"
}

Sample Query

query {
  _admin_session {
    message
  }
}

_env

Query to get all the environment variables.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

{
  "x-authorizer-admin-secret": "ADMIN_SECRET"
}

All the environment variables values can be obtained using this this.

Sample Query

query {
  _env {
    DATABASE_TYPE
    DATABASE_URL
    DATABASE_NAME
    CLIENT_ID
   CLIENT_SECRET
    ...
  }
}

_webhook

Query to get webhook by its identifier. This query is allowed for admins only. It accepts params of type WebhookRequest with following keys and returns Webhook

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

Response

Sample Query

query {
  _webhook(params: { id: "123-adfa-123412-asdfasda" }) {
    id
    event_name
  }
}

_webhooks

Query to get list of webhooks. This query is allowed for admins only.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

It can take optional params input of type PaginatedInput with following keys

Request Params

Response

It returns response of type Webhooks with following keys

Sample Query

 
_webhooks(params: {limit: 10, page: 1}) {
  pagination {
    limit
    offset
    total
  }
  webhooks {
    id
    event_name
    endpoint
  }
}
 

_webhook_logs

Query to get list of webhook logs. This query is allowed for admins only.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

It can take optional params input of type ListWebhookLogRequest with following keys

Request Params

Response

It returns response of type WebhookLogs with following keys

Sample Query

 
_webhook_logs(params: {
  pagination: {
    limit: 10
  }
  webhook_id: "test"
}) {
  pagination {
    limit
    offset
    total
  }
  webhook_logs {
    id
    http_status
    request
    response
    webhook_id
  }
}
 

_email_templates

Query to get list of email templates. This query is allowed for admins only.

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

It can take optional params input of type PaginatedInput with following keys

Request Params

Response

It returns response of type EmailTemplates with following keys

Sample Query

 
_email_templates(params: {limit: 10, page: 1}) {
  pagination {
    limit
    offset
    total
  }
  webhooks {
    id
    template
    event_name
    created_at
    updated_at
  }
}
 

Mutations

signup

A mutation to signup users using email and password. It accepts params of type SignUpInput with following keys as parameter. Either email or phone_number is required to singup

Request Params

This mutation returns AuthResponse type with following keys

Response

Sample Mutation

mutation {
  signup(
    params: { email: "foo@bar.com", password: "test", confirm_password: "test" }
  ) {
    message
  }
}

login

A mutation to login users using email and password. It accepts params of type LoginInput with following keys as parameter. Either email or phone_number is required to login

Note: To enable MFA, go to dashboard and enable MFA for user. By default, TOTP MFA will be enabled. If SMTP deatils are provided then Mail OTP can also be enabled. One can only enable one MFA at a time. For TOTP verification use verify_totp mutation, and for verifying mail OTP use verify_otp mutation.

Request Params

This mutation returns AuthResponse type with following keys

Response

Sample Mutation

mutation {
  login(params: { email: "foo@bar.com", password: "test" }) {
    user {
      email
      given_name
      family_name
      picture
      roles
    }
    access_token
    expires_in
    message
  }
}

magic_link_login

A mutation to perform password less login. It accepts params of type MagicLinkLoginInput with following keys as parameter. When the operation is successful, it sends user email with magic link to login. This link is valid for 30 minutes only.

Note: You will need a SMTP server with an email address and password configured as authorizer environment using which system can send emails.

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  magic_link_login(params: { email: "foo@bar.com" }) {
    message
  }
}

logout

Mutation to logout user. This is authorized request and accepts token as HTTP cookie or Authorization header with Bearer token. This action clears the session data from server. It returns Response type with following keys

Response

Sample Mutation

mutation {
  logout {
    message
  }
}

update_profile

Mutation to update profile of user. It accepts params of type UpdateProfileInput with following keys as parameter

Note: this is authorized route and Authorization with bearer access token is required

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  update_profile(params: { given_name: "bob" }) {
    message
  }
}

verify_email

Mutation to verify email address of user. It accepts params of type VerifyEmailInput with following keys as parameter

Request Params

This mutation returns AuthResponse type with following keys

Response

Sample Mutation

mutation {
  verify_email(params: { token: "some token" }) {
    user {
      email
      given_name
      family_name
      picture
    }
    access_token
    expires_in
    message
  }
}

resend_verify_email

Mutation to resend verification email. This is helpful if user does not receive verification email. It accepts params of type ResendVerifyEmailInput with following keys as parameter

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  resend_verify_email(
    params: { email: "foo@bar.com", identifier: "basic_auth_signup" }
  ) {
    message
  }
}

forgot_password

Mutation to reset the password in case user have forgotten it. For security reasons this is 2 step process, we send email to the registered and then the are redirect to reset password url through the link in that email. In the first step, it accepts params of type ForgotPasswordInput with following keys as parameter

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  forgot_password(params: { email: "foo@bar.com" }) {
    message
  }
}

reset_password

Mutation to reset the password. For security reasons this is 2 step process, we send email to the registered and then the are redirect to reset password url through the link in that email. In the second step, it accepts params of type ResetPasswordInput with following keys as parameter

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  reset_password(
    params: { token: "some token", password: "test", confirm_password: "test" }
  ) {
    message
  }
}

revoke

Mutation to revoke refresh token.

Request Params

mutation {
  revoke(params: { refresh_token: "token" }) {
    message
  }
}

verify_otp

Mutation to verify OTP sent to the user. It accepts params of type VerifyOTPRequest with following keys as parameter

Request Params

Either email or phone_number is required

This mutation returns AuthResponse type with following keys

Response

Sample Mutation

mutation {
  verify_otp(params: { email: "foo@bar.com", otp: "AB123C" }) {
    user {
      email
      given_name
      family_name
      picture
      roles
    }
    access_token
    expires_in
    message
  }
}

resend_otp

Mutation to resend OTP to the user. It accepts params of type ResendOTPRequest with following keys as parameter

Request Params

Either email or phone_number is required

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  resend_otp(params: { email: "foo@bar.com" }) {
    message
  }
}

verify_totp

Mutation to verify TOTP generated by QR code. It accepts params of type VerifyTOTPRequest with following keys as parameter

Request Params

This mutation returns AuthResponse type with following keys

Response

Sample Mutation

mutation {
  verify_totp(params: { token: "token", otp: "AB123C" }) {
    user {
      email
      given_name
      family_name
      picture
      roles
    }
    access_token
    expires_in
    message
  }
}

deactivate_account

Mutation to deactiavte the user account deactivate_account. It returns Response type with the following keys.

Note: this is authorized route, so Authorization Header with bearer access token must be present or HTTPs cookie should be present.

Response

Sample Mutation

mutation {
  deactivate_account {
    message
  }
}

_admin_signup

Mutation to signup administrator. This only works if ADMIN_SECRET env is not set. It accepts params of type AdminSignupInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

This mutation returns Response type with message

Sample Mutation

mutation {
  _admin_signup(params: { admin_secret: "some string" }) {
    message
  }
}

_admin_login

Mutation to login administrator. It accepts params of type AdminLoginInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

This mutation returns Response type with message

Sample Mutation

mutation {
  _admin_login(params: { admin_secret: "some string" }) {
    message
  }
}

_admin_logout

Mutation to logout administrator. It does not have any params

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

This mutation returns Response type with message

Sample Mutation

mutation {
  _admin_logout {
    message
  }
}

_update_env

Mutation to update environment variables. It accepts params of type UpdateEnvInput with keys present in environment variables

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

This mutation returns Response type with message

Sample Mutation

mutation {
  _update_env(params: { DATABASE_URL: "data.db", DATABASE_TYPE: "sqlite" }) {
    message
  }
}

_update_user

Mutation to update the profile of users. This mutation is only allowed for super admins. It accepts params of type UpdateUserInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

{
  "x-authorizer-admin-secret": "ADMIN_SECRET"
}

Request Params

This mutation returns User type with update values

Sample Mutation

mutation {
  _update_user(
    params: { id: "20", given_name: "Bob", roles: ["user", "admin"] }
  ) {
    id
    given_name
    roles
    createdAt
    updatedAt
  }
}

_delete_user

Mutation to delete user. This mutation is only allowed for super admins. It accepts params of type DeleteUserInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  _delete_user(params: { email: "foo@bar.com" }) {
    message
  }
}

_invite_members

Mutation to invite members. This mutation is only allowed for super admins. It accepts params of type InviteMemberInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  _invite_members(params: { emails: ["foo@yopmail.com"] }) {
    message
  }
}

_revoke_access

Mutation to revoke access of a given user. This mutation is only allowed for super admins. It accepts params of type UpdateAccessInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  _revoke_access(params: { user_id: "test" }) {
    message
  }
}

_enable_access

Mutation to enable access of a given user whose access revoked earlier. This mutation is only allowed for super admins. It accepts params of type UpdateAccessInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

This mutation returns Response type with following keys

Response

Sample Mutation

mutation {
  _enable_access(params: { user_id: "test" }) {
    message
  }
}

_generate_jwt_keys

Mutation to generate new jwt keys based on given jwt algorithm. This mutation is only allowed for super admins. It accepts params of type GenerateJWTKeysInput with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

This mutation returns GenerateJWTKeysResponse type with following keys

Response

Sample Mutation

mutation {
  _generate_jwt_keys(params: { type: "RS256" }) {
    public_key
    private_key
  }
}

_test_endpoint

Mutation to test webhook endpoint. This mutation is allowed for admins only. It accepts params of type TestEndpointRequest with following keys and returns TestEndpointResponse

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

It sends following data to your webhook with POST method

{
  "event_name": "user.login", // whatever is called
  "user": {}, // [user object](https://docs.authorizer.dev/core/graphql-api#profile)
  "auth_recipe": "basic_auth" // optional key sent for signup / login event to describe the login/signup method used.
}

Response

Sample Mutation

mutation {
  _test_endpoint(params: {
    event_name: "user.login",
    endpoint: "https://foo.com/webhook",
    headers: {"Authorization": "Basic test"}
  }) {
    http_status
    response
  }
}

_add_webhook

Mutation to add webhook. This mutation is allowed for admins only. It accepts params of type AddWebhookRequest with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

It sends following data to your webhook with POST method

{
  "event_name": "user.login", // whatever is called
  "user": {}, // [user object](https://docs.authorizer.dev/core/graphql-api#profile)
  "auth_recipe": "basic_auth" // optional key sent for signup / login event to describe the login/signup method used.
}

Response

Sample Mutation

mutation {
  _add_webhook(params: {
    event_name: "user.login",
    endpoint: "https://foo.com/webhook",
    enabled: true,
    headers: {"Authorization": "Basic test"}
  }) {
    message
  }
}

_update_webhook

Mutation to update webhook. This mutation is allowed for admins only. It accepts params of type UpdateWebhookRequest with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

Response

Sample Mutation

mutation {
  _update_webhook(params: {
    id: "123-adfa-123412-asdfasda",
    event_name: "user.login",
    endpoint: "https://foo.com/webhook",
    enabled: true,
    headers: {"Authorization": "Basic test"}
  }) {
    message
  }
}

_delete_webhook

Mutation to delete webhook. This mutation is allowed for admins only. It accepts params of type WebhookRequest with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

Response

Sample Mutation

mutation {
  _delete_webhook(params: { id: "123-adfa-123412-asdfasda" }) {
    message
  }
}

_add_email_template

Mutation to add email template that will be used while sending emails. This mutation is allowed for admins only. It accepts params of type AddEmailTemplateRequest with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

Response

Sample Mutation

mutation {
  _add_email_template(
    params: { event_name: "user.login", template: "hello world" }
  ) {
    message
  }
}

_update_email_template

Mutation to update email template. This mutation is allowed for admins only. It accepts params of type UpdateEmailTemplateRequest with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

Response

Sample Mutation

mutation {
  _update_email_Template(
    params: {
      id: "123-adfa-123412-asdfasda"
      event_name: "update_email"
      template: "Welcome back!"
    }
  ) {
    message
  }
}

_delete_email_template

Mutation to delete email template. This mutation is allowed for admins only. It accepts params of type DeleteEmailTemplateRequest with following keys

Note: the super admin query can be access via special header with super admin secret (this is set via ENV) or authorizer-admin as http only cookie.

Request Params

Response

Sample Mutation

mutation {
  _delete_email_template(params: { id: "123-adfa-123412-asdfasda" }) {
    message
  }
}