authorization - instasport/club-api GitHub Wiki

Регистрация и авторизация

Клиент регистрируется в системе один раз. Регистрация – это создание клиента в системе.

Авторизация – это получение доступа в систему. Чтобы авторизоваться в системе клиенту нужно ввести телефон и код из смс.

Если клиент заходит в приложение хотя бы раз в 30 дней, то ему не нужно авторизоваться (вводить телефон и код из смс). Если клиент не заходил в приложение больше месяца, то ему нужно будет авторизоваться еще раз (данные регистрации остаются прежними).

Технически это достигается за счет использования двух токенов – access token и refresh token. После авторизации, приложение получает оба токена. Все вызовы функций делаются с помощью access token. У этого токена короткий срок действия (например 5 минут).

Если при вызове функции происходит ошибка, то нужно проверить код ошибки. Если access token закончился, то будет выдана ошибка – закончился токен доступа. В этом случае необходимо воспользоваться вторым токеном (refresh token) и вызвать функцию обновления токенов. В результате мы получим два новых токена.

Срок действия токена обновления 30 дней. И если обновлять токены чаще, чем один раз в 30 дней, то их можно продлевать сколько угодно раз.

Для получения access token необходимо авторизовать существующего клиента или зарегистрировать нового клиента. Срок действия access token достаточно короткий, для его возобновления необходимо воспользоваться refresh token

Обновление токенов

Если закончился срок действия access token, то токены можно обновить, вызвав tokenRefresh

При этом обновляются оба токена (access token и refresh token)

Если закончился срок действия refresh token, то нужно авторизоваться по новой.

mutation TokenRefresh {
  tokenRefresh {
    token {
      accessToken
      refreshToken
    }
  }
}

Запрос

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { phoneVerify(phone: \"+380670000000\", code: \"0000\") {token {accessToken refreshToken}}}" }' https://instasport.co/api/

Ответ

{"data":{"phoneVerify":{"token":{"accessToken":"804670f5fbd794658918b3d97bc423d3ca92caf9","refreshToken":"2f0c944b66ac6acd3c4c6417ac24082252fdcd23"}}}}

Запрос

curl -X POST -H "Content-Type: application/json" -H "Authorization: Refresh 2f0c944b66ac6acd3c4c6417ac24082252fdcd23" --data '{ "query": "mutation { tokenRefresh {token {accessToken refreshToken}}}" }' https://instasport.co/api/

Ответ

{"data":{"tokenRefresh":{"token":{"accessToken":"0fb6dc4ce11344a7cad5861bd90bfae4aa8f4e0d","refreshToken":"3548ab78f7b6eafaba720daacd7360ac95bbe165"}}}}

Чтение личных данных

Для доступа к личным данным необходимо быть авторизованным в системе и иметь access token.

С помощью этой функции можно прочитать все личные данные, кроме пароля (пароль в системе хранится в виде хэш значения).

query User {
  user {
    id
    phone
    email
    firstName
    lastName
    birthday
    gender
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token d87dfe18c5b287d9a5f1b614f4fa5e0d3bb6a0ab test" --data '{ "query": "{ user {id, phone, email, firstName, lastName, birthday, gender} }" }' https://instasport.co/api/

Изменение личных данных

Для изменения личных данных необходимо быть авторизованным в системе и иметь access token

С помощью этой функции можно изменять все личные данные (включая пароль), кроме телефона, email и аватара.

mutation UserUpdate {
  userUpdate(first_name: "Test", last_name: "Test", password: "1234", birthday: "1986-08-11", gender: 0) {
    user {
      id
      firstName
      lastName
      gender
      birthday
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token 7d9a5574fa45c8181c47073ef0aaa125bc228d09 test" --data '{ "query": "mutation { userUpdate(firstName: \"Test\", lastName: \"Test\", password: \"1234\", gender: 0, birthday: \"1986-08-11\") {user { id firstName lastName gender birthday }}}" }' https://instasport.co/api/

Изменение аватара

Для изменения аватара необходимо быть авторизованным в системе и иметь access token

Особенность запроса в том, что отправляется form-data в body с 2 полями:

  1. query="mutation{userAvatarUpdate(input:{}){success}}"
  2. avatar=Файл

Пример curl запроса ниже

curl --location --request POST 'https://instasport.co/api/' --header 'Authorization: Token cca994997b110ca95acf9ed7c224a67d99952e7f' --form 'avatar=@"filepath"' --form 'query="mutation{userAvatarUpdate(input:{}){success}}"'

Ответ:

{
    "data": {
        "userAvatarUpdate": {
            "success": "true"
        }
    }
}

Если всё хорошо, если была ошибка - "success": "false"

Изменение телефона

Для изменения телефона необходимо быть авторизованным в системе (иметь access token) и иметь подтвержденный email. Если email не будет подтвержден, то есть шанс потерять доступ к аккаунту.

Новый телефон не должен быть зарегистрирован (подтвержден) в системе.

После вызова phoneUpdate, телефон клиента изменится на новый. Новый телефон будет в статус - не подтвержден. Для подтверждения телефона будет выслан смс с кодом на новый телефон. Далее нужно вызвать phoneVerify и указать полученный код. Если этого не сделать, то авторизоваться через телефон уже будет нельзя (ни через новый, ни через старый). Для восстановления доступа к аккаунту можно воспользоваться авторизацией через email.

Функция phoneUpdate возвращает поле ok. Это поле нет необходимости проверять. Если произойдет ошибка, то ничего не вернется, а если успех, то всегда ok == True

mutation PhoneUpdate {
  phoneUpdate(phone: "+380670000000") {
    ok
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token 456b0c56b45ccda18d23892f497fea1fa9389375 test" --data '{ "query": "mutation { phoneUpdate(phone: \"+380670000000\") {ok}}" }' https://instasport.co/api/

Изменение e-mail

Для изменения email необходимо быть авторизованным в системе и иметь access token

После вызова emailUpdate будет послано письмо на указанный email

Если клиент нажмет на ссылку из письма, то email обновится

Параметр next обязателен. После нажатия на ссылку из письма, будет редирект на этот адрес.

Функция emailUpdate возвращает поле ok. Это поле нет необходимости проверять. Если произойдет ошибка, то ничего не вернется, а если успех, то всегда ok == True

mutation EmailUpdate {
  emailUpdate(email: "[email protected]", next: "https://instasport.co") {
    ok
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Token ab210fb1c59372e216b940985bd1273b5530549d test" --data '{ "query": "mutation { emailUpdate(email: \"[email protected]\",  next: \"https://instasport.co\") {ok}}" }' https://instasport.co/api/

Регистрация нового клиента по телефону

Регистрация нового клиента происходит в два запроса. Сначала phoneSignup - создает нового клиента и высылает код в смс. Потом PhoneVerify - сравнивает код из смс и возвращает токены (access_token и refresh_token).

При вызове phoneSignup необходимо указать телефон, который еще не зарегистрирован (не подтвержден) и личные данные (имя, фамилия).

При регистрации создается профиль клиента в клубе (если он еще не создан). Если профиль уже был, то профиль не изменяется.

После этого высылается смс с кодом.

Если функция регистрации вызывается повторно с тем же самым телефоном, то старые данные перезаписываются на новые. Так будет происходить до тех пор, пока телефон не будет подтвержден.

Обязательные параметры

phone (в формате +38067...)
firstName (строка)
lastName (строка)
origin (число)

Поле origin указывает как был зарегистрирован клиент

0 - неизвестно
2 - c помощью email на сатйе Instasport
3 - с помощью телефона на сайте Instasport
4 - c помощью Facebook на сайте Instasport
5 - с помощью email на сайте клуба (плагин)
6 - с помощью телефона на сайте клуба (плагин)
7 - с помощью Facebook на сайте клуба (плагин)
9 - с помощью телефона из приложения клуба
10 - с помощью email из приложения клуба
11 - с помощью Facebook из приложения клуба

Дополнительные параметры

birthday (строка в формате "YYYY-MM-DD")
gender (число)

Поле gender указывает пол

0 - неизвестно
1 - парень
2 - девушка

mutation PhoneSignup {
  phoneSignup(phone: "+380670000000", firstName: "Test", lastName: "Test", birthday: "1986-08-11", gender: 0, origin: 0) {
    user {
      id
      firstName
      lastName
      gender
      birthday
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { phoneSignup(phone: \"+380670000000\", firstName: \"Test\", lastName: \"Test\", origin: 0) {user { id firstName lastName }}}" }' https://instasport.co/api/

Для подтверждения телефона необходимо вызвать функцию верификации.

mutation PhoneVerify {
  phoneVerify(phone: "+380670000000", code: "0000") {
    token {
      accessToken
      refreshToken
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { phoneVerify(phone: \"+380670000000\", code: \"0000\") {token {accessToken refreshToken}}}" }' https://instasport.co/api/

Авторизация клиента по телефону

Авторизация проходит в 2 запроса. Сначала PhoneLogin - проверяется есть ли клиент в базе и если есть, то высылается код в смс. Потом PhoneVerify - сравнивает код из смс и возвращает токены (access_token и refresh_token).

Можно использовать тестовый аккаунт с номером +380670000000, там всегда работает код 0000

mutation PhoneLogin {
  phoneLogin(phone: "+380670000000") {
    user {
      id
      firstName
      lastName
      gender
      birthday
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { phoneLogin(phone: \"+380670000000\") {user { id firstName lastName }}}" }' https://instasport.co/api/

Для проверки телефона необходимо вызвать функцию верификации.

mutation PhoneVerify {
  phoneVerify(phone: "+380670000000", code: "0000") {
    token {
      accessToken
      refreshToken
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { phoneVerify(phone: \"+380670000000\", code: \"0000\") {token {accessToken refreshToken}}}" }' https://instasport.co/api/

Регистрация нового клиента по e-mail

При вызове emailSignup необходимо указать email, который еще не зарегистрирован (не подтвержден) и личные данные (пароль, имя, фамилия).

При регистрации создается профиль клиента в этом клубе (если он еще не создан). Если профиль уже был, то профиль не изменяется.

После этого высылается письмо на почту, в котором нужно нажать на ссылку для подтверждения указанной почты.

Если указывается параметр next, то после нажатия на ссылку из письма, будет редирект на этот адрес. Если next не указан, то будет переход на профиль клиента в системе (если указан клуб, то на профиль в клубе).

Если функция регистрации вызывается повторно с тем же самым email, то старые данные перезаписываются на новые. Так будет происходить до тех пор, пока email не будет подтвержден.

Обязательные параметры

email (строка)
password (строка)
firstName (строка)
lastName (строка)
origin (число)

Дополнительные параметры

birthday (строка в формате "YYYY-MM-DD")
gender (число)

mutation EmailSignup {
  emailSignup(email: "[email protected]", password: "1234", firstName: "Test", lastName: "Test", gender: 0, next: "https://instasport.co", origin: 0) {
    user {
      id
      firstName
      lastName
      gender
      birthday
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { emailSignup(email: \"[email protected]\", password: \"1234\", firstName: \"Test\", lastName: \"Test\", next: \"https://instasport.co\", origin: 0) {user { id firstName lastName }}}" }' https://instasport.co/api/

Авторизация клиента по e-mail

Для авторизации нужно указать email и пароль. В случае успеха, будут возвращены токены доступа.

mutation EmailVerify {
  emailVerify(email: "[email protected]", password: "1234") {
    token {
      accessToken
      refreshToken
    }
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { emailVerify(email: \"[email protected]\", password: \"1234\") {token { accessToken refreshToken }} }" }' https://instasport.co/api/

Сброс пароля по e-mail

Для сброса пароля необходимо указать email, который зарегистрирован в системе. На этот адрес придет письмо со ссылкой. Если нажать на эту ссылку, то можно будет ввести новый пароль.

Если указывается параметр next, то после ввода нового пароля, будет редирект на этот адрес. Если next не указан, то будет переход на профиль клиента в клубе.

Функция emailReset возвращает поле ok. Это поле нет необходимости проверять. Если произойдет ошибка, то ничего не вернется, а если успех, то всегда ok == True

mutation EmailReset {
  emailReset(email: "[email protected]", next: "https://instasport.co") {
    ok
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { emailReset(email: \"[email protected]\") {ok}}" }' https://instasport.co/api/

Объединение аккаунтов

Для объединение аккаунтов необходимо указать email, который зарегистрирован в системе. На этот адрес придет письмо со ссылкой. Если нажать на эту ссылку, то можно текущий аккаунт и с указанным email объединятся.

Если указывается параметр next, то будет редирект на этот адрес. Если next не указан, то будет переход на профиль клиента в клубе.

Функция emailMerge возвращает поле ok. Это поле нет необходимости проверять. Если произойдет ошибка, то ничего не вернется, а если успех, то всегда ok == True

mutation EmailMerge {
  emailMerge(email: "[email protected]", next: "https://instasport.co") {
    ok
  }
}

curl -X POST -H "Content-Type: application/json" -H "Authorization: Key Ajsgwf3SLdcGpiXLPpzc29poWermmEkR6/xNqkS4onk= test" --data '{ "query": "mutation { emailMerge(email: \"[email protected]\") {ok}}" }' https://instasport.co/api/

Рекомендованная последовательность регистрации/авторизации клиента

Для входа в систему мы просим ввести телефон. Если клиент уже есть в системе, то ему придет код из смс. Если клиента нет в системе, то мы его регистрируем.

После получения токенов доступа (access_token и refresh_token) мы можем попросить клиента ввести email

Экран 1 (Login)

Просим клиента ввести телефон и вызываем phoneLogin

Если клиент найден, то переходим на Экран 3 (Verify)

Если клиента нет, то переходим на Экран 2 (Signup)

Экран 2 (Signup)

Клиент вводит личные данные и мы вызываем phoneSignup и переходим на Экран 3 (Verify)

Экран 3 (Verify)

Здесь клиент должен ввести код из смс и мы вызываем phoneVerify

Если код неверный, то выдаем сообщение об ошибке. У клиента должна быть возможность вернуться на предыдущий экран.

Если код правильный, то мы получаем токены доступа (access_token и refresh_token) и считываем данные клиента, чтобы узнать есть ли email и подтвержден ли он

query User {
  user {
    email
    emailConfirmed
  }
}

Если нет подтвержденного email, то переходим на Экран 4 (Ввод E-mail). Если подтвержденный email есть, то переходим на Экран 7 (Welcome).

Экран 4 (Ввод E-mail)

На этом экране у клиента нет подтвержденного email. Просим клиента ввести email и вызываем функцию emailUpdate

Если такой email уже зарегистрирован в системе и он зарегистрирован в другом аккаунте (код ошибки 3), то нам нужно выполнить объединение аккаунтов - переходим на Экран 5 (Объединение аккаунтов).

Если такого email еще нет в системе, то переходим на Экран 6 (Ожидание подтверждения E-mail)

Экран 5 (Объединение аккаунтов)

Спрашиваем хочет ли клиент объединить аккаунты и если да, то вызываем emailMerge и переходим на Экран 6 (Ожидание подтверждения E-mail)

При вызове emailMerge отправляется письмо на email. Если нажать на ссылку из этого письма, то произойдет объединение аккаунтов и возврат в приложение.

Экран 6 (Ожидание подтверждения E-mail)

После нажатия ссылки в письме клиент возвращается в приложение на этот экран.

Мы проверяем подтвержден ли email, вызывая функцию чтения данных User и если да, то переходим на Экран 7 (Welcome)

Экран 7 (Welcome)

Клиент авторизовался/зарегистрирован в системе.