API Documentation

Quick Links

• GraphQL Playground (IDE)
• GraphQL Voyager (Schema Explorer)
• Using GraphQL Playground
• Using GraphQL Voyager
• API Operations
  • Queries
  • Mutations
  • Subscriptions
• Tracker Permission Levels
  • User
  • Admin
  • Super Admin

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
      }
    }
  }
}

3. Copy the JWT from the authToken field:

{
  "data": {
    "signIn": {
      "result": {
        "authToken": "<token to by copied>"
      }
    }
  }
}

4. 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>"
}

5. 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:

   • Navigate to GraphQL Voyager (Schema Explorer)
   • Click "Change Schema”.
   • Click the "Introspection" tab.
   • Click “Copy Introspection Query”.

2. Execute introspection query agains target GraphQL endpoint:

   • Go to GraphQL Playground (IDE)
   • Paste introspection query into the request.
   • Issue the request.

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

API Operations

Queries

findDomainByDomain

• Query for a specific domain by providing a domain.
• Permissions: User Admin Super Admin
• Code

findMe

• Query the currently logged in user.
• Permissions: User Admin Super Admin
• Code

findMyDmarcSummaries

• Query for dmarc summaries the user has access to.
• Permissions: User Admin Super Admin
• Code

findMyDomains

• Query for domains the user has access to.
• Permissions: User Admin Super Admin
• Code

findMyOrganizations

• Query for organizations the user has access to.
• Permissions: User Admin Super Admin
• Code

findOrganizationBySlug

• Query for a specific organizations by providing a slug.
• Permissions: User Admin Super Admin
• Code

findUserByUserName

• Query for a specific user by providing a username.
• Permissions: Admin Super Admin
• Code

isUserAdmin

• Query to check if requesting user has an admin permission level.
• Permissions: User Admin Super Admin
• Code

isUserSuperAdmin

• Query to check if requesting user has a super admin permission level.
• Permissions: User Admin Super Admin
• Code

mailSummary

• Query for email summary computed values, used to build summary cards.
• Permissions: User Admin Super Admin
• Code

webSummary

• Query for web summary computed values, used to build summary cards.
• Permissions: User Admin Super Admin
• Code

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

• Allows user to create a new domain for an organization.
• Permissions: User Admin Super Admin
• Code

createOrganization

• Allows user to create a new organization.
• Permissions: User Admin Super Admin
• Code

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

• Allows users to leave a given organization.
• Permissions: User Admin Super Admin
• Code

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

• Allows the removal of a domain from a given organization.
• Permissions: Admin Super Admin
• Code

removeOrganization

• Allows the removal of unused organizations.
• Permissions: Admin Super Admin
• Code

removePhoneNumber

• Allows requesting user to remove phone number from their account.
• Permissions: User Admin Super Admin
• Code

removeUserFromOrg

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

requestScan

• Allows user to request an instant one-time scan on a requested domain.
• Permissions: User Admin Super Admin
• Code

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

• Allows a user to sign out and clear their cookies.
• Permissions: User Admin Super Admin
• Code

signUp

• Allows new users to sign up for the sites services.
• Permissions: User Admin Super Admin
• Code

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

• Allows the user to update their account password.
• Permissions: User Admin Super Admin
• Code

updateUserProfile

• Allows the user to update various profile attributes.
• Permissions: User Admin Super Admin
• Code

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

• Allows the user to receive text message TFA codes.
• Permissions: User Admin Super Admin
• Code

Subscriptions

dkimScanData

• Allows user to receive DKIM one-time scan results.
• Permissions: User Admin Super Admin
• Code

dmarcScanData

• Allows user to receive DMARC one-time scan results.
• Permissions: User Admin Super Admin
• Code

httpsScanData

• Allows user to receive HTTPS one-time scan results.
• Permissions: User Admin Super Admin
• Code

spfScanData

• Allows user to receive SPF one-time scan results.
• Permissions: User Admin Super Admin
• Code

sslScanData

• Allows user to receive SSL one-time scan results.
• Permissions: User Admin Super Admin
• Code

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.