Skip to content

API Documentation

Luke Campbell edited this page May 24, 2022 · 15 revisions

Quick Links

Using GraphQL Playground

GraphQL Playground provides an easy to use interface with the Tracker API allowing developers and users to write custom Queries, Mutations, and Subscriptions for development and testing purposes.

Getting Started

To use Tracker's GraphQL API, the user will first need to authenticate themselves to access protected content, to do this follow these steps:

  1. Visit Tracker GraphQL Playground

  2. Authenticate your account using the signIn mutation:

mutation {
  signIn (input: {
    userName: "<username>"
    password: "<password>"
  }) {
    result {
      ... on AuthResult {
        authToken
      }
      ... on TFASignInResult {
        sendMethod
        authenticateToken
      }
    }
  }
}

2.5. If the user has TFA enabled they will have to execute the following mutation:

mutation {
  authenticate (input: {
    authenticationCode: "<TFA code received through text or email>"
    authenticateToken: "<token pasted from authenticateToken field>"
  }) {
    result {
      ... on AuthResult {
        authToken
      }
    }
  }
}
  1. Copy the JWT from the authToken field:
{
  "data": {
    "signIn": {
      "result": {
        "authToken": "<token to by copied>"
      }
    }
  }
}
  1. Once you have copied the token you will need to paste it in the HTTP Headers Field that can be found on the bottom left of the IDE, in the following format:
{
  "authorization": "<token pasted here>"
}
  1. You will now be able to execute various Queries, Mutations, and Subscriptions. Example Query:
query {
  findMyDomains(
    first: 5
    orderBy: { field: DOMAIN, direction: ASC }
    search: "cyber.gc.ca"
  ) {
    edges {
      node {
        id
        domain
      }
    }
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
  }
}

Using GraphQL Voyager

With GraphQL Voyager you can visually explore your GraphQL API as an interactive graph. This is a great tool when designing or discussing your data model.

How to use

  1. Obtain specially crafted introspection query:

  2. Execute introspection query agains target GraphQL endpoint:

  3. Copy and paste obtained GraphQL schema to Voyager and click "Display".

API Operations

Queries

findDomainByDomain

findMe

findMyDmarcSummaries

findMyDomains

findMyOrganizations

findOrganizationBySlug

findUserByUserName

isUserAdmin

isUserSuperAdmin

mailSummary

webSummary

Mutations

authenticate

  • Allows users to give their credentials and retrieve a token that gives them access to restricted content.
  • Permissions: User Admin Super Admin
  • Code

closeAccount

  • Allows a user to close their account, or a super admin to close another user's account.
  • Permissions: User Admin Super Admin
  • Code

createDomain

createOrganization

inviteUserToOrg

  • Allows admins and higher to invite users to any of their organizations, if the invited user does not have an account, they will be able to sign-up and be assigned to that organization in one mutation.
  • Permissions: Admin Super Admin
  • Code

leaveOrganization

refreshTokens

  • Allows users to give their current auth token, and refresh token, and receive a freshly updated auth token.
  • Permissions: User Admin Super Admin
  • Code

removeDomain

removeOrganization

removePhoneNumber

removeUserFromOrg

  • Allows admins or super admins to remove users from any of their affiliated organizations.
  • Permissions: Admin Super Admin
  • Code

requestScan

resetPassword

  • Allows requesting user to take a token received in their email to reset their password.
  • Permissions: User Admin Super Admin
  • Code

sendEmailVerification

  • Allows user to re-send a verification if it failed or timed-out after account creation.
  • Permissions: User Admin Super Admin
  • Code

sendPasswordResetLink

  • Allows a user to provide their username and request that a password reset link be sent to their email.
  • Permissions: User Admin Super Admin
  • Code

setPhoneNumber

  • Allows requesting user to set a new phone number, and as well sending a code to verify the given phone number.
  • Permissions: User Admin Super Admin
  • Code | User Admin Super Admin

signIn

  • Allows users to give their credentials and either sign them in or re-direct them to a TFA form.
  • Permissions: User Admin Super Admin
  • Code

signOut

signUp

transferOrgOwnership

  • Allows user to transfer organization ownership to another user in the given organization.
  • Permissions: Admin Super Admin
  • Code

updateDomain

  • Allows the modification of a domain for any updates it requires through out its lifetime.
  • Permissions: User Admin Super Admin
  • Code

updateOrganization

  • Allows the modification of an organization if any changes occur throughout its lifetime.
  • Permissions: Admin Super Admin
  • Code

updateUserPassword

updateUserProfile

updateUserRole

  • Allows admins and super admins to update a users permission level on a given organization.
  • Permissions: Admin Super Admin
  • Code

verifyAccount

  • Allows users to email verify their account. Providing additional functionality to their account.
  • Permissions: User Admin Super Admin
  • Code

verifyOrganization

  • Allows super admins to verify an organization.
  • Permissions: Super Admin
  • Code

verifyPhoneNumber

Subscriptions

dkimScanData

dmarcScanData

httpsScanData

spfScanData

sslScanData

Tracker Permission Levels

  • Tracker has three different permissions a user can have, they are User, Admin, and Super Admin.
  • These permissions are stored in the users affiliation to the given organization.
  • This allows users to have different permissions levels for different organizations depending on the users needs.

User

The User permission level is the lowest level that a registered user can have. The User permission grants the following functionality:

  • Ability to view a given organization
  • View the given organizations domains and related scans
  • Add/Update domains to the organization
  • Request scans on domains

Admin

The Admin permission level is the middle level that a registered user can have, it may also be referred as Org Admin The Admin permission grants the following functionality:

  • All user level abilities to view given organization
  • View the given organization affiliated users
  • Remove domains from the organization
  • Invite/Update/Remove users from the organization at user or admin level

Super Admin

The Super Admin permission level is the highest level of permissions a registered user can have. This permission level gives the user the ability to do anything in Tracker other then user account related functionality.

Clone this wiki locally