{"_id":"56c418c854b6030d00ec29a2","category":{"_id":"56c4180d70187b17005f43b4","__v":5,"project":"56bc8e679afb8b0d00d62dcf","version":"56bc8e689afb8b0d00d62dd2","pages":["56c418c854b6030d00ec29a2","56c418e670187b17005f43b7","56c418efc4796b0d007ef03a","56c418f94040602b0064cea1","56ca81146b58fb0b00c6d2fc"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-17T06:49:49.187Z","from_sync":false,"order":1,"slug":"buddy-basics","title":"Buddy Basics"},"parentDoc":null,"__v":7,"project":"56bc8e679afb8b0d00d62dcf","user":"56b98db7bb36440d0001f492","version":{"_id":"56bc8e689afb8b0d00d62dd2","project":"56bc8e679afb8b0d00d62dcf","__v":18,"createdAt":"2016-02-11T13:36:40.146Z","releaseDate":"2016-02-11T13:36:40.146Z","categories":["56bc8e689afb8b0d00d62dd3","56c3c837bc41330d009f25ed","56c3c83e521f350d00d348eb","56c3c8452d97560d00e23cd8","56c3c85234df460d00c2beb8","56c4180d70187b17005f43b4","56c418162d97560d00e23cf6","56c4181cc4796b0d007ef039","56c4182370187b17005f43b5","56c418292e75e01700986052","56c4183328bd680d005e7ac6","56c4183bbb64720d00552b88","56c418414040602b0064cea0","56c4184754b6030d00ec29a1","56c4184c28bd680d005e7ac7","56c4185370187b17005f43b6","56c4185b6063071700500cfc","582a98b6f8c0a0190053d7a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-17T06:52:56.738Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"## Overview\n\n### iOS, Android, .NET, JavaScript SDKs\n\nFor the Buddy SDKs, service authentication is handled automatically by the SDK.\n\n### REST/HTTP\n\nMost calls to the Buddy server will require the client to be authenticated.\n\nThe Buddy service supports two authorization mechanisms: \n- Credentials (App ID/App Key, for device registration only)\n- An access token (Device or User token, for all other calls)\n\nAn Access Token is a string that is given to a client in exchange for some information that  the client provides to the server.  They are opaque to the client, but contain client information as well as an expiration date.\n\nThere are currently two types of Access Token in Buddy (See below for more details on each)\n\n- Device Access Token\n- User Access Token\n\n### Authenticating with App Credentials\nApp credentials consist of an App ID and an App Key, which are generated by the Buddy Dashboard when an App is created.  You can retrieve these from your app's Overview or Settings page.  \n\nThese should be kept private and never sent over insecure channels; if someone else obtains your App ID and Key, then they can access your App's data.\n\nCredentials can be sent to the Buddy server and exchanged for a device access token (see below).\n\nApp credentials are only valid on device registration (`POST /devices`, details below).  If verified, you will be returned a device access token.\n\n### Authenticating with an Access Token\n\nTo use an access token, simply take the Access Token (either App or User) and include its value in the HTTP Authorization like this:\n\n`Authorization: Buddy [accessToken]` (don't include the brackets!)\n\nFor example:\n\n`Authorization: Buddy xxxasfsadfasqce4`\n\n### Device Access Tokens\n\nA client obtains an device access token by presenting its app credentials (App ID and AppKey) to the server, thus proving it should be allowed to access the specific application.\n\n`Note`: To best protect your users, we recommend communicating with Buddy strictly through HTTPS.\n\nA device Access Token allows access to *App Level resources* on the Buddy server e.g.:\n\n- Record Metric\n- Create User\n- Login User\n- Set Metadata (`App` visibility)\n\nTo obtain a device access token, send a POST to /devices (**NOTE** the Buddy SDK's for the various platforms take care of this for you)\n\n    POST /devices\n     {\n       appid: '[your app id]',\n       appkey: '[your app key]',\n       platform: 'REST Client'\n     }\n\nA response from the server will look like this:\n\n    {\n      \"status\": 201,\n      \"result\": {\n        \"accessToken\": \"[access Token]\",\n        \"accessTokenExpires\": \"/Date(1422514769546)/\"\n      },\n     \"request_id\": \"b625b290-cf69-405d-8091-b2c0f25a08c7\"\n    }\n\nwhere the *accessTokenExpires* field is the expiration of the *accessToken* (in milliseconds since 1/1/1970)\n\nThe *accessToken* can then be provided back to the server (see below) to access *App-Level* resources.\n\n#### Registering Apps In Remote Regions\n\nIf your application is hosted in a remote region, such as Buddy EU, then the response will look like this:\n\n    {\n      \"status\": 201,\n      \"result\": {\n        \"accessToken\": \"[access Token]\",\n        \"accessTokenExpires\": \"/Date(1422514769546)/\",\n        \"serviceRoot\" : \"https://api-some-region.buddyplatorm.com\"\n      },\n     \"request_id\": \"b625b290-cf69-405d-8091-b2c0f25a08c7\"\n    }\n\nWhere `serviceRoot` is the endpoint that you **MUST** use for subsequent calls.  The accessToken that is returned is **only** valid for that region and can **not** be used for calls to the main region.  \n\nThe Buddy SDKs handle this automatically, but for HTTP callers, the client must remember both the accessToken and the serviceRoot for subsequent calls, were serviceRoot is substituted for the standard `https://api.buddyplatform.com` base URL.  So in the example above, a user login would then go to `https://api-some-region.buddyplatform.com/login/users` rather than `https://api.buddyplatform.com/login/users`.\n\n### User Access Tokens\n\nTo access user-level resources, a user access token must be obtained.   This can be done in one of two ways:\n\n- createUser (POST /users)\n- login (POST /users/login)\n\nIn each case, the App needs to supply its device access token plus the required parameters for the operation (username/password) etc, in exchange for the User Access Token\n\n***Note*** While a client will generally only use one device access token at a time, multiple User Access Tokens could be used concurrently (if the App was working with multiple users for example).\n\nAn example of obtaining a User Access Token is: \n\n    POST /users\n          Headers:\n              Content-Type: application/json\n              Authorization: Buddy [token]\n          Body:\n          {\n            username: 'buddy',\n            password: 'a.password',\n            email: \"buddy:::at:::buddydemo.com\",\n            firstName: 'Buddy',\n            lastName: 'Demo'\n         }\n\nThis call results in something like:\n\n    {\n    \"status\": 200,\n    \"result\": {\n        \"celebMode\": false,\n        \"locationFuzzing\": false,\n        \"accessToken\": \"[accessToken]\",\n        \"accessTokenExpires\": \"/Date(1422515312708)/\",\n        \"firstName\": \"Buddy\",\n        \"lastName\": \"Demo\",\n        \"lastLogin\": \"/Date(1390979312700)/\",\n        \"email\": \"[email protected]\",\n        \"userName\": \"buddy\",\n        \"id\": \"bv.gnkbbmsbqsJg\",\n        \"created\": \"/Date(1390979312510)/\",\n        \"lastModified\": \"/Date(1390979312700)/\"\n        },\n       \"request_id\": \"7b22e8af-f623-4618-8f18-5c8fe1e2aff8\"\n    }\n\nNote the `accessToken` and `accessTokenExpires` attributes.\n\nThe majority of Buddy API calls require a User Token.  If you attempt to call an API with an App Token, the Buddy server will send a response code of `403 (Forbidden)`, and a Buddy error code of `AuthUserAccessTokenRequired`.  \n\n***NOTE*** A User Access token also implicitly acts as a device access token (i.e. it can be used to access App Level resources like Metrics)\n\n### Security Considerations\n\nAccess Tokens are considered secret information, as they allow access to your apps on the Buddy server. Therefore it's important to keep them secure.\n\n- Only transmit them over https\n- Never email them or post them in a public place\n\n### Expiration and Revocation\n\nAs mentioned above, all Access Tokens have an expiration. If a Token is presented to the Buddy server past that expiration date, then access will not be granted.\n\nOnce a token expires, it should no longer be used, and a new token can be obtained as outlined earlier in this document.\n\nThere are also circumstances in which a token will be revoked, preventing further use:\n\n* User logout\n* User deletion\n* Security events (e.g. an app's security is compromised)\n\nBuddy does not guarantee that tokens will remain valid until their expiration date, so it's important for your code to be structured to properly handle expired tokens.\n\n### Common Authentication Errors\n\nHere is a list of common authentication errors that can occur, expressed in the JSON as returned from Buddy. These can occur when processing application credentials (the App ID and App Key), or device or user Access Tokens. The request ID will be unique to the request. If you are using an SDK these values will be in the result of the call to Buddy, either in a return value, or as a parameter to a callback, depending on the SDK. \n\n###### Password must be at least 4 characters:\n{\n  \"status\": 400,\n  \"error\": \"ParameterOutOfRange\",\n  \"errorNumber\": 514,\n  \"message\": \"Parameter Password. Password must be at least 4 characters\",\n  \"request_id\": \"576db321cbfb4304e038011a\"\n}\n\n###### The specified user name already exists; user names must be unique:\n{\n  \"status\": 400,\n  \"error\": \"ItemAlreadyExists\",\n  \"errorNumber\": 770,\n  \"message\": \"The value for parameter UserName already exists. Choose a unique one.\",\n  \"request_id\": \"576db4d1ebcc6e0f80309723\",\n  \"success\": false\n}\n\n###### Either the user name does not exist, or the password is incorrect:\n{\n  \"status\": 403,\n  \"error\": \"AuthBadUsernameOrPassword\",\n  \"errorNumber\": 262,\n  \"request_id\": \"576db517ebcc6e0f8030b5d3\",\n  \"success\": false\n}\n\n###### The App ID is malformed:\n{\n  \"status\": 401,\n  \"error\": \"ParameterOutOfRange\",\n  \"errorNumber\": 514,\n  \"message\": \"Incorrect id type, expected App\",\n  \"request_id\": \"576db68cf658d109386f657e\"\n}\n\n###### The App ID or key is incorrect:\n{\n  \"status\": 401,\n  \"error\": \"AuthAppCredentialsInvalid\",\n  \"errorNumber\": 261,\n  \"message\": \"The supplied AppId or AppKey is invalid, please double check the values.\",\n  \"request_id\": \"576dbf6d3745ef0c343883ae\"\n}\n\n###### An Access Token either has expired, or has been revoked. Additionally, this error will result if a user Access Token is used after it has been used to log out the user:\n{\n  \"status\": 401,\n  \"error\": \"AuthAccessTokenInvalid\",\n  \"errorNumber\": 261,\n  \"message\": \"Incorrect token type.\",\n  \"request_id\": \"576dbf6d3745ef0c343883ae\"\n}\n\n###### Not passing a user token when one is needed:\n{\n  \"status\": 403,\n  \"error\": \"AuthUserAccessTokenRequired\",\n  \"errorNumber\": 263,\n  \"request_id\": \"576dce9c1d04f80d6c4645f6\"\n}","excerpt":"","slug":"service-authentication","type":"basic","title":"Service Authentication"}

Service Authentication


## Overview ### iOS, Android, .NET, JavaScript SDKs For the Buddy SDKs, service authentication is handled automatically by the SDK. ### REST/HTTP Most calls to the Buddy server will require the client to be authenticated. The Buddy service supports two authorization mechanisms: - Credentials (App ID/App Key, for device registration only) - An access token (Device or User token, for all other calls) An Access Token is a string that is given to a client in exchange for some information that the client provides to the server. They are opaque to the client, but contain client information as well as an expiration date. There are currently two types of Access Token in Buddy (See below for more details on each) - Device Access Token - User Access Token ### Authenticating with App Credentials App credentials consist of an App ID and an App Key, which are generated by the Buddy Dashboard when an App is created. You can retrieve these from your app's Overview or Settings page. These should be kept private and never sent over insecure channels; if someone else obtains your App ID and Key, then they can access your App's data. Credentials can be sent to the Buddy server and exchanged for a device access token (see below). App credentials are only valid on device registration (`POST /devices`, details below). If verified, you will be returned a device access token. ### Authenticating with an Access Token To use an access token, simply take the Access Token (either App or User) and include its value in the HTTP Authorization like this: `Authorization: Buddy [accessToken]` (don't include the brackets!) For example: `Authorization: Buddy xxxasfsadfasqce4` ### Device Access Tokens A client obtains an device access token by presenting its app credentials (App ID and AppKey) to the server, thus proving it should be allowed to access the specific application. `Note`: To best protect your users, we recommend communicating with Buddy strictly through HTTPS. A device Access Token allows access to *App Level resources* on the Buddy server e.g.: - Record Metric - Create User - Login User - Set Metadata (`App` visibility) To obtain a device access token, send a POST to /devices (**NOTE** the Buddy SDK's for the various platforms take care of this for you) POST /devices { appid: '[your app id]', appkey: '[your app key]', platform: 'REST Client' } A response from the server will look like this: { "status": 201, "result": { "accessToken": "[access Token]", "accessTokenExpires": "/Date(1422514769546)/" }, "request_id": "b625b290-cf69-405d-8091-b2c0f25a08c7" } where the *accessTokenExpires* field is the expiration of the *accessToken* (in milliseconds since 1/1/1970) The *accessToken* can then be provided back to the server (see below) to access *App-Level* resources. #### Registering Apps In Remote Regions If your application is hosted in a remote region, such as Buddy EU, then the response will look like this: { "status": 201, "result": { "accessToken": "[access Token]", "accessTokenExpires": "/Date(1422514769546)/", "serviceRoot" : "https://api-some-region.buddyplatorm.com" }, "request_id": "b625b290-cf69-405d-8091-b2c0f25a08c7" } Where `serviceRoot` is the endpoint that you **MUST** use for subsequent calls. The accessToken that is returned is **only** valid for that region and can **not** be used for calls to the main region. The Buddy SDKs handle this automatically, but for HTTP callers, the client must remember both the accessToken and the serviceRoot for subsequent calls, were serviceRoot is substituted for the standard `https://api.buddyplatform.com` base URL. So in the example above, a user login would then go to `https://api-some-region.buddyplatform.com/login/users` rather than `https://api.buddyplatform.com/login/users`. ### User Access Tokens To access user-level resources, a user access token must be obtained. This can be done in one of two ways: - createUser (POST /users) - login (POST /users/login) In each case, the App needs to supply its device access token plus the required parameters for the operation (username/password) etc, in exchange for the User Access Token ***Note*** While a client will generally only use one device access token at a time, multiple User Access Tokens could be used concurrently (if the App was working with multiple users for example). An example of obtaining a User Access Token is: POST /users Headers: Content-Type: application/json Authorization: Buddy [token] Body: { username: 'buddy', password: 'a.password', email: "[email protected]", firstName: 'Buddy', lastName: 'Demo' } This call results in something like: { "status": 200, "result": { "celebMode": false, "locationFuzzing": false, "accessToken": "[accessToken]", "accessTokenExpires": "/Date(1422515312708)/", "firstName": "Buddy", "lastName": "Demo", "lastLogin": "/Date(1390979312700)/", "email": "[email protected]", "userName": "buddy", "id": "bv.gnkbbmsbqsJg", "created": "/Date(1390979312510)/", "lastModified": "/Date(1390979312700)/" }, "request_id": "7b22e8af-f623-4618-8f18-5c8fe1e2aff8" } Note the `accessToken` and `accessTokenExpires` attributes. The majority of Buddy API calls require a User Token. If you attempt to call an API with an App Token, the Buddy server will send a response code of `403 (Forbidden)`, and a Buddy error code of `AuthUserAccessTokenRequired`. ***NOTE*** A User Access token also implicitly acts as a device access token (i.e. it can be used to access App Level resources like Metrics) ### Security Considerations Access Tokens are considered secret information, as they allow access to your apps on the Buddy server. Therefore it's important to keep them secure. - Only transmit them over https - Never email them or post them in a public place ### Expiration and Revocation As mentioned above, all Access Tokens have an expiration. If a Token is presented to the Buddy server past that expiration date, then access will not be granted. Once a token expires, it should no longer be used, and a new token can be obtained as outlined earlier in this document. There are also circumstances in which a token will be revoked, preventing further use: * User logout * User deletion * Security events (e.g. an app's security is compromised) Buddy does not guarantee that tokens will remain valid until their expiration date, so it's important for your code to be structured to properly handle expired tokens. ### Common Authentication Errors Here is a list of common authentication errors that can occur, expressed in the JSON as returned from Buddy. These can occur when processing application credentials (the App ID and App Key), or device or user Access Tokens. The request ID will be unique to the request. If you are using an SDK these values will be in the result of the call to Buddy, either in a return value, or as a parameter to a callback, depending on the SDK. ###### Password must be at least 4 characters: { "status": 400, "error": "ParameterOutOfRange", "errorNumber": 514, "message": "Parameter Password. Password must be at least 4 characters", "request_id": "576db321cbfb4304e038011a" } ###### The specified user name already exists; user names must be unique: { "status": 400, "error": "ItemAlreadyExists", "errorNumber": 770, "message": "The value for parameter UserName already exists. Choose a unique one.", "request_id": "576db4d1ebcc6e0f80309723", "success": false } ###### Either the user name does not exist, or the password is incorrect: { "status": 403, "error": "AuthBadUsernameOrPassword", "errorNumber": 262, "request_id": "576db517ebcc6e0f8030b5d3", "success": false } ###### The App ID is malformed: { "status": 401, "error": "ParameterOutOfRange", "errorNumber": 514, "message": "Incorrect id type, expected App", "request_id": "576db68cf658d109386f657e" } ###### The App ID or key is incorrect: { "status": 401, "error": "AuthAppCredentialsInvalid", "errorNumber": 261, "message": "The supplied AppId or AppKey is invalid, please double check the values.", "request_id": "576dbf6d3745ef0c343883ae" } ###### An Access Token either has expired, or has been revoked. Additionally, this error will result if a user Access Token is used after it has been used to log out the user: { "status": 401, "error": "AuthAccessTokenInvalid", "errorNumber": 261, "message": "Incorrect token type.", "request_id": "576dbf6d3745ef0c343883ae" } ###### Not passing a user token when one is needed: { "status": 403, "error": "AuthUserAccessTokenRequired", "errorNumber": 263, "request_id": "576dce9c1d04f80d6c4645f6" }