Back to top

API Documentation

Authentication

These routes deal with authentication.

Register by Email

Register by Email
POST/v1/auth/register/email

Register a new user with an email and password. Returns an access token. Additionally, and email will be sent to the user asking them to verify their email address.

Example URI

POST /v1/auth/register/email
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "first_name": "George",
  "last_name": "Washington",
  "email": "george.washington@example.com",
  "email_type": "work",
  "password": "5VphcVNdGhJi",
  "password_confirmation": "5VphcVNdGhJi"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string",
      "description": "User First Name."
    },
    "last_name": {
      "type": "string",
      "description": "User Last Name."
    },
    "email": {
      "type": "string",
      "description": "User Email address."
    },
    "email_type": {
      "type": "string",
      "enum": [
        "work",
        "personal"
      ],
      "description": "The User Email type"
    },
    "password": {
      "type": "string",
      "description": "User Password. Between 8 and 64 characters."
    },
    "password_confirmation": {
      "type": "string",
      "description": "User Password test.  Must equal property 'password'."
    }
  },
  "required": [
    "first_name",
    "last_name",
    "email",
    "email_type",
    "password",
    "password_confirmation"
  ]
}
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  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."
        }
      ],
      "email_type": [
        {
          "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": {
            "first_name": {
              "type": "array"
            },
            "last_name": {
              "type": "array"
            },
            "email": {
              "type": "array"
            },
            "email_type": {
              "type": "array"
            },
            "password": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Login by Email

Login by Email
POST/v1/auth/login/email

Login with the current user.

Example URI

POST /v1/auth/login/email
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "george.washington@example.com",
  "password": "5VphcVNdGhJi"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "User Email address."
    },
    "password": {
      "type": "string",
      "description": "User Password. Between 8 and 64 characters."
    }
  },
  "required": [
    "email",
    "password",
    "email",
    "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": {
      "password": [
        {
          "message": "The value in this field is not valid."
        }
      ],
      "email": [
        {
          "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": {
            "password": {
              "type": "array"
            },
            "email": {
              "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": "555-555-5555",
        "phone_type": "work",
        "primary": true,
        "verified": false,
        "created_at": "2016-05-03T10:41:31.257Z",
        "updated_at": "2016-05-03T10:41:31.257Z"
      }
    ]
  },
  "emails": {
    "data": [
      {
        "id": 1,
        "email": "george.washington@example.com",
        "email_type": "work",
        "primary": true,
        "verified": false,
        "created_at": "2016-05-03T10:41:31.257Z",
        "updated_at": "2016-05-03T10:41:31.257Z"
      }
    ]
  },
  "created_at": "2016-05-03T10:41:31.257Z",
  "updated_at": "2016-05-03T10:41:31.257Z"
}
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"
        }
      }
    },
    "created_at": {
      "type": "string",
      "description": "The created date in ISO8601 format"
    },
    "updated_at": {
      "type": "string",
      "description": "The updated date in ISO8601 format"
    }
  },
  "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 user. The email will contain a uri to deep link the user into the application where they can then enter a new password. The deep link will embed a code and a verification type of password. This code can then be used when making the call to Reset Password. Depending on the verification method, the contact parameter in the link will either be the email address or cell phone number the notification was sent to.

If the verification method of email is used:

  • The link will be in the following format: scale-tickets.app://scale-tickets.app/password_reset?code=12345&contact=george.washington@gmail.com.

If the verification method of cell is used:

  • The link will be in the following format: scale-tickets.app://scale-tickets.app/password_reset?code=12345&contact=7015555678.

Example URI

POST /v1/auth/password/forgot
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "contact_method": "email",
  "contact": "george.washington@gmail.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contact_method": {
      "type": "string",
      "enum": [
        "email",
        "cell"
      ],
      "description": "The verification method used to send the password reset notification"
    },
    "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

This endpoint is to be used after calling the Forgot Password endpoint. Upon the user successfully opening either an email message or a text message which routes them to the deep link similar to the one listed in that section, that code can be used to store a new password for the user by replacing the existing one.

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

Signup

Signup
POST/v1/auth/signup

Sign up for the application using the user’s email address or cell phone number. The endpoint will respond with an access token and its associated expiration date.

If the user selects contact method email:

  • A verification email will be sent to the email address given so the user can authenticate their email address. The link will be in the following format: scale-tickets.app://scale-tickets.app/email_verification?code=12345&contact=george.washington@gmail.com.

If the user selects contact method cell:

  • A verification text message will be sent to the number given so the user can authenticate their cell phone number. The link will be in the following format: scale-tickets.app://scale-tickets.app/cell_verification?code=12345&contact=7015551879.

This code and contact provided in the link can then be used when making the call to Verify Code

Example URI

POST /v1/auth/signup
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "contact_method": "email",
  "contact": "george.washington@gmail.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "contact_method": {
      "type": "string",
      "enum": [
        "email",
        "cell"
      ],
      "description": "The contact method used to send the notification"
    },
    "contact": {
      "type": "string",
      "description": "The user's email address or cell phone number to send the notification to"
    }
  }
}
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  422
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have validation errors in your submission",
    "validation_messages": {
      "contact_method": [
        {
          "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": {
            "contact_method": {
              "type": "array"
            },
            "contact": {
              "type": "array"
            }
          }
        }
      }
    }
  }
}

Verify Code

Verify Code
POST/v1/auth/verify

This endpoint is to be used after calling the Signup endpoint. Upon the user successfully opening the email message or text message which routes them to the app via a deep link as described in that section, the code and contact can be used to authenticate the user to the provided email address or cell phone.

Example URI

POST /v1/auth/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
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 04 May 2016