Back to top

API Documentation

Authentication

These routes deal with authentication.

Register

Register
POST/v1/auth/register

Start the registration process for a new user. The user must submit either a phone number or an email, but not both. A verification text message will be sent to them if they enter a phone number. Likewise a verification meail message will be sent to them if they submit an email address. Upon successful completion of verification process, a new user will be created.

Example URI

POST /v1/auth/register
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "first_name": "george",
  "last_name": "washington",
  "phone": "555-665-4345",
  "type": "personal",
  "password": "IWasTheFirstPrez1776",
  "password_confirmation": "IWasTheFirstPrez1776",
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Registration request",
  "description": "A request to register with the system",
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string",
      "description": "The user's first name."
    },
    "last_name": {
      "type": "string",
      "description": "The user's last name."
    },
    "phone": {
      "type": "string",
      "description": "The user's phone number."
    },
    "email": {
      "type": "string",
      "description": "The user's email address."
    },
    "type": {
      "description": "The type of contact method.",
      "enum": ["work", "personal"]
    },
    "password": {
      "type": "string",
      "description": "The password the user wishes to have."
    },
    "password_confirmation": {
      "type": "string",
      "description": "Confirmation of the above password. These must match."
    }
  },
  "required": [
    "first_name",
    "last_name",
    "type",
    "password",
    "password_confirmation"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have validation errors in your submission",
    "validation_messages": {
      "first_name": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "last_name": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "email": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "phone": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "type": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "password": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "password_confirmation": [
        {
          "message": "The value in this field is not valid."
        }
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "validation_messages": {
          "type": "object",
          "properties": {
            "first_name": {
              "type": "array"
            },
            "last_name": {
              "type": "array"
            },
            "email": {
              "type": "array"
            },
            "phone": {
              "type": "array"
            },
            "type": {
              "type": "array"
            },
            "password": {
              "type": "array"
            },
            "password_confirmation": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Login

Login
POST/v1/auth/login

Login with the current user with either an email address or a phone number.

Example URI

POST /v1/auth/login
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "contact": "george.washington@example.com",
  "password": "5VphcVNdGhJi"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contact": {
      "type": "string",
      "description": "The user's email address or phone number."
    },
    "password": {
      "type": "string",
      "description": "The user's password."
    }
  },
  "required": [
    "contact",
    "password"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "access_token": "48a4034027374be582b936f7d58043af",
    "expires": "2016-05-03T11:15:54.950Z"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "access_token": {
          "type": "string",
          "description": "The access token to be used to authenticate future requests"
        },
        "expires": {
          "type": "string",
          "description": "The datetime when the access token will expire"
        }
      },
      "required": [
        "expires"
      ]
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "AUTHENTICATION_FAILED",
    "error": "Invalid Credentials",
    "more": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The code indicating authentication failure"
        },
        "error": {
          "type": "string",
          "description": "The error message indicating invalid credentials"
        },
        "more": {
          "type": "object",
          "properties": {}
        }
      }
    }
  }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have validation errors in your submission",
    "validation_messages": {
      "contact": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "password": [
        {
          "message": "The value in this field is not valid."
        }
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "validation_messages": {
          "type": "object",
          "properties": {
            "contact": {
              "type": "array"
            },
            "password": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Me

Me
GET/v1/auth/me

Get the currently logged in user’s information.

Example URI

GET /v1/auth/me
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "first_name": "George",
  "last_name": "Washington",
  "last_login": "2016-05-03T12:21:25.858Z",
  "phones": {
    "data": [
      {
        "id": 1,
        "phone": "5556439875",
        "phone_type": "work",
        "primary": true
      }
    ]
  },
  "emails": {
    "data": [
      {
        "id": 1,
        "email": "george.washington@example.com",
        "email_type": "work",
        "primary": true
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the entity"
    },
    "first_name": {
      "type": "string",
      "description": "User First Name."
    },
    "last_name": {
      "type": "string",
      "description": "User Last Name."
    },
    "last_login": {
      "type": "string",
      "description": "The date of the user's last successful login"
    },
    "phones": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array"
        }
      }
    },
    "emails": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array"
        }
      }
    }
  },
  "required": [
    "first_name",
    "last_name"
  ]
}

Change Password

Change Password
PUT/v1/auth/password/change

Change the user’s password

Example URI

PUT /v1/auth/password/change
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "existing_password": "oldpassword",
  "new_password": "newpassword",
  "new_password_confirmation": "newpassword"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "existing_password": {
      "type": "string",
      "description": "The user's old password"
    },
    "new_password": {
      "type": "string",
      "description": "The user's new password"
    },
    "new_password_confirmation": {
      "type": "string",
      "description": "The user's new password confirmation. This must match 'new_password'."
    }
  },
  "required": [
    "existing_password",
    "new_password",
    "new_password_confirmation"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "INVALID_EXISTING_PASSWORD",
    "error": "Invalid existing password",
    "more": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The existing password is invalid"
        },
        "error": {
          "type": "string",
          "description": "Error for existing password invalidity"
        },
        "more": {
          "type": "object",
          "properties": {}
        }
      }
    }
  }
}

Forgot Password

Forgot Password
POST/v1/auth/password/forgot

Send an email or text message to the user containing a verification code. The verification code can then be used in combination with the email or phone number to reset the user’s password’.

Example URI

POST /v1/auth/password/forgot
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "contact": "george.washington@gmail.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contact": {
      "type": "string",
      "description": "The user's email address or cell phone number to send the notification to"
    }
  },
  "required": [
    "contact"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Reset Password

Reset Password
PUT/v1/auth/password/reset

Reset the user’s password. This endpoint is to be used after calling the Forgot Password endpoint. The code is the verification code that was sent to the user via either text message or email.

Example URI

PUT /v1/auth/password/reset
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "contact": "george.washington@gmail.com",
  "code": "12345",
  "password": "5VphcVNdGhJi",
  "password_confirmation": "5VphcVNdGhJi"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contact": {
      "type": "string",
      "description": "The user's email address or cell phone number that the verification notification was sent to"
    },
    "code": {
      "type": "string",
      "description": "The password reset code that was sent to the user via their chosen notification method"
    },
    "password": {
      "type": "string",
      "description": "User Password. Between 8 and 64 characters."
    },
    "password_confirmation": {
      "type": "string",
      "description": "User Password test.  Must equal property 'password'."
    }
  },
  "required": [
    "contact",
    "code",
    "password",
    "password_confirmation"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "INVALID_CODE",
    "error": "Invalid CODE",
    "more": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The code is invalid"
        },
        "error": {
          "type": "string",
          "description": "Error for invalid code"
        },
        "more": {
          "type": "object",
          "properties": {}
        }
      }
    }
  }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have validation errors in your submission",
    "validation_messages": {
      "code": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "contact": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "password": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "password_confirmation": [
        {
          "message": "The value in this field is not valid."
        }
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "validation_messages": {
          "type": "object",
          "properties": {
            "code": {
              "type": "array"
            },
            "contact": {
              "type": "array"
            },
            "password": {
              "type": "array"
            },
            "password_confirmation": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Send Verification Code

Send Verification Code
POST/v1/auth/verification_codes/send

Send a verification code to the user’s email address or cell phone number. This code can then be used when making the call to Verify Verification Code

Example URI

POST /v1/auth/verification_codes/send
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "george.washington@example.com",
  "phone": "555-555-5555"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": [
        "string",
        "null"
      ],
      "description": "The user's email address to send the notification to."
    },
    "phone": {
      "type": [
        "string",
        "null"
      ],
      "description": "The user's phone number to send the notification to."
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have validation errors in your submission",
    "validation_messages": {
      "email": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "phone": [
        {
          "message": "The value in this field is not valid."
        }
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "validation_messages": {
          "type": "object",
          "properties": {
            "email": {
              "type": "array"
            },
            "phone": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Verify Verification Code

Verify Verification Code
POST/v1/auth/verification_codes/verify

This endpoint is to be used after calling the Send Verification Code endpoint. Upon the user successfully opening the email message or text message and obtaining the authorization code, the code and contact can be used to authenticate the user to the provided email address or cell phone. The endpoint will respond with an access token and its associated expiration date.

Example URI

POST /v1/auth/verification_codes/verify
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "contact": "george.washington@gmail.com",
  "code": "12345"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contact": {
      "type": "string",
      "description": "The user's email address or cell phone number that the verification notification was sent to"
    },
    "code": {
      "type": "string",
      "description": "The password reset code that was sent to the user via their chosen notification method"
    }
  },
  "required": [
    "contact",
    "code"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "access_token": "48a4034027374be582b936f7d58043af",
    "expires": "2016-05-03T11:15:54.950Z"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "access_token": {
          "type": "string",
          "description": "The access token to be used to authenticate future requests"
        },
        "expires": {
          "type": "string",
          "description": "The datetime when the access token will expire"
        }
      },
      "required": [
        "expires"
      ]
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "code": "INVALID_CODE",
    "error": "Invalid CODE",
    "more": {}
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The code is invalid"
        },
        "error": {
          "type": "string",
          "description": "Error for invalid code"
        },
        "more": {
          "type": "object",
          "properties": {}
        }
      }
    }
  }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have validation errors in your submission",
    "validation_messages": {
      "code": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "contact": [
        {
          "message": "The value in this field is not valid."
        }
      ]
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "validation_messages": {
          "type": "object",
          "properties": {
            "code": {
              "type": "array"
            },
            "contact": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Generated by aglio on 20 Jan 2022