-
Notifications
You must be signed in to change notification settings - Fork 0
Accounts
Accounts describes the OAuth2 connected account of a User. There can be multiple Accounts associated with each User, but each Account can only belong to a single User.
The Account resource is represented in responses under the accounts property. The accounts property will be an array of Accounts.
Accounts appear as follows:
{
"added": datetime,
"id": uint64,
"provider": string,
"foreign_id": string,
"email": string,
"email_verified": bool,
"display_name": string,
"given_name": string,
"family_name": string,
"picture": string,
"locale": string,
"timezone": string,
"gender": string
}
None of these properties may be modified through interactions with the API—they are all provided by the OAuth provider or generated by the system and immutable.
- added: The date and time the account was first used to log into the system, expressed according to RFC 3339.
- id: A unique, immutable identifier for this user.
- provider: A string identifying the provider that the user used to log in. For version one, this will always be "google".
- foreign_id: the unique identifier the account is identified by in the provider's system.
- email: The email the provider supplied for the account.
- email_verified: True if the provider maintains that the email they supplied is "verified", False or omitted otherwise.
- display_name: the name of the account that should be displayed to the user when listing accounts.
- given_name: the given, or first, name of the user, according to the provider. May be omitted if the provider does not supply a given name.
- family_name: the family, or last, name of the user, according to the provider. May be omitted if the provider does not supply a family name.
- picture: a string containing a URL to an avatar, supplied by the provider. May be omitted in the event that the provider does not supply an avatar.
- locale: a string containing a locale code supplied by the provider. May be omitted if the provider does not supply a locale.
- timezone: a string containing the timezone supplied by the provider. May be omitted if the provider does not supply a timezone.
- gender: a string specifying the gender of the user, according to the provider. May be omitted if the provider does not supply a gender.
GET /accounts/redirect
The following URL parameters are required when starting the OAuth flow:
- callback: a URL-encoded URL that the user should be redirected to after they've granted access to their account with the provider.
This API call will respond with a 302 status code, redirecting the user to the provider's authorisation endpoint. Once the user authorises the system to retrieve their name and email address, they will be redirected back to the system, where the system will check for an account that matches the foreign ID supplied by the provider.
If no account matching the provider's foreign ID is found, a new Account will be created for the user, and the system will redirect the user to the URL specified in the callback parameter specified. When redirecting, the following parameters will be added to the callback URL:
- id: the ID of the Account that was created.
- email: the email address supplied by the provider.
- givenName: the given, or first, name supplied by the provider.
- familyName the family, or last, name supplied by the provider.
If an account matching the provider's foreign ID is found, the user is trying to log in, not register. The system will redirect the user to the URL specified in the callback parameter specified. When redirecting, the following parameters will be added to the callback URL:
- user: the username of the User associated with this account.
- secret: the secret for the User associated with this account.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | callback | Callback query param not specified |
| 400 | ERROR_INVALID_VALUE | callback | Callback is not a valid URL |
| 400 | ERROR_INVALID_FORMAT | callback | Callback has a % not followed by two hexadecimal digits. |
If an OAuth token has already been obtained for the account (through the Android accounts API, for example), authentication can be done in the typical request/response paradigm, instead of using callbacks.
POST /accounts/auth
The request body should contain the OAuth2 access token, refresh token, and the expiration date and time of the access token (formatted according to RFC 3339). The refresh token and expiration date are optional, and may be omitted.
A sample request body:
{
"tokens": {
"access": "access token goes here",
"refresh": "refresh token goes here",
"expires": "2010-12-02T22:47:31-05:00"
}
}
The response to this request is the User associated with the Account, if the foreign ID of the account specified by the OAuth token exists in the system (a "known" Account). Otherwise, the response is a collection of information about the Account that was created for the user (a "new" Account).
For New Accounts, this request sets the Last-Modified header to the current time and date.
For Known Accounts, this request sets the Last-Modified header to the added property of the Account returned.
For New Accounts, the Content-Type of the response will be accounts/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be accounts/json.
For Known Accounts, the Content-Type of the response will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
For New Accounts, the status code will be 201. For Known Accounts, the status code will be 200.
New Accounts return an array of a single Account resource:
{
"code": 201,
"msg": "Successfully created a new account",
"accounts": [
{
// See the Account Resource for the contents of this part
}
]
}
Known Accounts return an array of a single User resource, the User associated with the Account:
{
"code": 200,
"msg": "Successfully authenticated the user",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_BAD_REQUEST_FORMAT | Request not valid JSON. | |
| 400 | ERROR_MISSING_PARAM | tokens.access | Access token not supplied. |
| 500 | ERROR_ACT_OF_GOD | Error during OAuth verification. | |
| 400 | ERROR_INVALID_VALUE | tokens.access | Invalid access token. |
If a user has a device they've already authenticated, they can skip the OAuth process when setting up another device. They need to generate a pair of temporary credentials, then use those credentials when authenticating the device.
GET /accounts/tmp
The following URL parameters are required when authenticating with temporary credentials:
- cred1: the first of the five digit temporary credentials.
- cred2: the second of the five digit temporary credentials.
Not that the designation of cred1 and cred2 is arbitrary—either credential may be placed in either parameter, so long as both credentials are present.
The response to this request is the User the temporary credentials belong to. Note that it is impossible to create a new Account or User using temporary credentials.
This request sets the Last-Modified header to the last_active property of the User returned. The Content-Type of the response will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a User Resource:
{
"code": 200,
"msg": "Successfully authenticated the user",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | One or both credentials were missing. | |
| 401 | ERROR_INVALID_VALUE | The credentials were not correct. |
If a user has a device they've already authenticated, they can generate a set of temporary credentials that will skip the OAuth process. These credentials will only be accepted for 5 minutes after their creation.
This request requires authentication.
POST /accounts/tmp
This request expects no request body.
The response to this request is an array of two five digit temporary credentials the user can use to gain access to their account.
This request sets the Last-Modified header to the current date and time. The Content-Type of the response will be credentials/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be credentials/json.
This request returns an array of strings:
{
"code": 201,
"msg": "Generated temporary credentials",
"credentials": ["cred1", "cred2"]
}
This request throws no special errors.
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
GET /users/{username}/accounts
This request sets the Last-Modified header to the latest added property of the Accounts returned.
The Content-Type of this request will be accounts/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be accounts/json.
This request returns a list of user resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of accounts",
"accounts": [
{
// See the Account Resource for the contents of this part
},
{
// See the Account Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | Username not specified in URL. |
| 403 | ERROR_ACCESS_DENIED | User does not have access to the specified user's accounts. | |
| 404 | ERROR_NOT_FOUND | Specified user not found. |
This request requires only authentication if it is run against account owned by the authenticating user. If it is run against another user's account, it requires administrative credentials.
This request will repopulate the information associated with the Account from the provider, using the access token and refresh token the system has stored with the Account.
POST /accounts/{id}
The request body should be empty.
This request sets the Last-Modified header to the current time and date.
The Content-Type of this request will be accounts/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be accounts/json.
This request returns a list of Account resources as a JSON array. The array will only have one item—the Account that was modified:
{
"code": 200,
"msg": "Successfully updated the account",
"accounts": [
{
// See the Account Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No account ID specified in URL |
| 400 | ERROR_INVALID_FORMAT | id | Account ID must be an integer. |
| 403 | ERROR_ACCESS_DENIED | User does not have access to the specified account. |
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
This request will automatically update the information in the Account with the latest information supplied by the provider, in addition to storing the new token information.
PUT /accounts/{id}
Because this request has a body, the Content-Type, and Content-Length headers need to be set. The Content-Type header should be set to application/json.
The request body should be a JSON object containing the access token, refresh token, and expiration (as a date and time, formatted according to RFC 3339).
A sample request body:
{
"tokens": {
"access": "access token goes here",
"refresh": "refresh token goes here",
"expires": "2010-12-02T22:47:31-05:00"
}
}
If the expiration of the access token is unknown, omit that property. If there is not a refresh token available, omit that property. The access token is required, however.
This request sets the Last-Modified header to the current date and time.
The Content-Type of this request will be accounts/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be accounts/json.
This request returns a list of Account resources as a JSON array. The array will only have one item—the Account that was modified:
{
"code": 200,
"msg": "Successfully updated the account tokens",
"accounts": [
{
// See the Account Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No account ID specified in URL. |
| 400 | ERROR_INVALID_FORMAT | id | Account ID must be specified as an integer. |
| 400 | ERROR_BAD_REQUEST_FORMAT | Request not valid JSON. | |
| 400 | ERROR_MISSING_PARAM | tokens.access | Access token not specified. |
| 403 | ERROR_ACCESS_DENIED | User does not have access to the specified account. |
This request requires only authentication if it is run against an account owned by the authenticating user. If it is run against another user's account, it requires administrative credentials.
DELETE /accounts/{id}
This request sets the Last-Modified header to the added property of the Account that was deleted.
The Content-Type of this request will be accounts/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be accounts/json.
This request returns a list of account resources as a JSON array. The array will only have one item—the Account that was just deleted:
{
"code": 200,
"msg": "Successfully deleted the account",
"accounts": [
{
// See the Account Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No account ID specified in URL. |
| 400 | ERROR_INVALID_FORMAT | id | Account ID must be specified as an integer. |
| 403 | ERROR_ACCESS_DENIED | User does not have access to that account. |