Skip to main content


Authentication involves verifying the identification of a user. The credentials of the user are matched against the credentials in the database. Users are generally identified with a user id or an email.

Authentication is important. It keeps the resources secure from unauthenticated users. The resources may include networks, databases, websites, and other applications.

Hypi provides authentication functions to its users. The functions are easy-to-use. You can create a password-protected account with a user name or an email. You can log in to the account with saved credentials.


createAccount is a mutation that creates a new user account. You need to provide the credentials of the user. It generates a new user account. This account can be used to login and perform various actions.

createAccount(value: AccountInput!): Hypi

Account is a data type (table) which holds the information of an account.

type Account {
hypi: Hypi
verified: Boolean
enabled: Boolean
username: String!
password: Password!
owner: Person
emails(...): [Email!]
phones(...): [Phone!]
groups(...): [Group!]
roles(...): [Role!]
attempts(...): [LoginAttempt!]
remoteLogins(...): [RemoteLogin!]

You may pass on parameters to the Account object to store Account information. E.g. username, password, emails, phone contacts, group details, role details. Hypi also stores the login attempts in this table. The Person type (owner parameter) stores the information of the user like name, address, date of birth, gender, etc. It also keeps the information whether the user has been authenticated in the Boolean fields verified and enabled.

Create a user account as shown in the below example. You may pass more parameters as required. The function returns the account id, the date of creation, and created by information from the created Account object.

mutation {
value: {
username: "[email protected]"
password: { value: "[email protected]" }
emails: [{ value: "[email protected]" }]
) {


Users may log in using the login function.

login(username:String!,password:String!): AccessToken

It takes a username and password as inputs. Successful login generates session token. The user has to use the session token to perform various actions. This function also returns the session expiry time. If any error comes during login, you may also get an error code and error message.

username: "[email protected]",
password: "[email protected]"
) {


Users may log in using the loginByEmail function. This function takes email-id and password as inputs. It also generates session-token and provides error code and error message if any.

loginByEmail(email: "[email protected]", password: "[email protected]") {

Token Refresh API

Token Refresh API facilitates the exchange of an expired token for a fresh one, eliminating the need for users to undergo the login process again. Using GET method, expired token can be refreshed to retrieve new token.

To utilize this API, the expired token needs to be passed by either of the following methods:

  • By setting the token as a query parameter, for instance: /auth/token?token=<the expired token>
  • By setting the Authorization header to the old token.


Upon successful execution, the API responds with a JSON object containing the new token:

"token": "<the new token>"

It is crucial to note that this API does not alter the permissions associated with the token. The newly generated token retains the same set of permissions as the old one—no more, no less.