Authentication

auth.createUser and auth.login authenticate students with an email address and password. Both mutations return a JWT (token) and expiresAt. Send the token on later requests as Authorization: Bearer <token>.

For domain-based integrations, Owlflow reads the Host header during registration and sign-in. Don't send a domain in the GraphQL input. Partner identification documents the hostname lookup.

If students don't sign in to ScholarshipOwl directly, generate a password per student on your server, pass it to auth.createUser, and store the returned user.id, token, and expiresAt.

Create an account

Include an Idempotency-Key header when creating an account through auth.createUser. Generate a new UUID for each registration attempt. If you retry the same attempt with the same key, Owlflow returns the original result instead of creating another account. Keep the key at 128 characters or fewer.

mutation Signup($input: CreateUserInput!) {
  auth {
    createUser(input: $input) {
      success
      token
      expiresAt
      user {
        id
        email
        firstName
        lastName
      }
      errors {
        code
        field
        message
      }
    }
  }
}

{
  "input": {
    "email": "ava@example.com",
    "password": "correct-horse-battery",
    "firstName": "Ava",
    "lastName": "Nguyen"
  }
}

auth.createUser requires the student's real email address in CreateUserInput.email because scholarship providers notify winners by email. Successful registration returns a token and signs the student in immediately.

If the email already exists on your partner domain, auth.createUser returns success: false and errors: [{ code: "EMAIL_ALREADY_EXISTS", field: "email" }]. Call auth.login to sign that student in.

Sign in

mutation Login($input: LoginInput!) {
  auth {
    login(input: $input) {
      token
      expiresAt
      user {
        id
        email
        firstName
        lastName
      }
    }
  }
}

LoginInput contains email, password, and the optional remember field.

Refresh and sign out

Tokens expire 24 hours after issue (expiresAt). auth.refreshToken accepts a valid or recently expired token for up to 7 days after it was issued and returns a new 24-hour token and expiresAt. Scheduled jobs that run every few days can call auth.refreshToken with the last Bearer <token> instead of signing in again. After 7 days, call auth.login.

mutation RefreshToken {
  auth {
    refreshToken {
      token
      expiresAt
      user {
        id
        email
      }
    }
  }
}

Call auth.logout to revoke the current token. Owlflow returns true when revocation succeeds.

mutation Logout {
  auth {
    logout
  }
}

Who is signed in

query CurrentUser {
  me {
    id
    email
    firstName
    lastName
  }
}