{"__v":16,"_id":"56a0bda13697d80d002ac600","category":{"__v":1,"_id":"56b098da8f7a4f0d0029dd10","pages":["56b0c05c0f5f980d0059fb91"],"project":"54774d9af3736008009e9e0e","version":"56a0bd9e3697d80d002ac5e7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-02T11:54:02.535Z","from_sync":false,"order":11,"slug":"syncano-basics","title":"Syncano Basics"},"parentDoc":null,"project":"54774d9af3736008009e9e0e","user":"54ad5f42921992210075173e","version":{"__v":20,"_id":"56a0bd9e3697d80d002ac5e7","project":"54774d9af3736008009e9e0e","createdAt":"2016-01-21T11:14:38.131Z","releaseDate":"2016-01-21T11:14:38.131Z","categories":["56a0bd9f3697d80d002ac5e8","56a0bd9f3697d80d002ac5e9","56a0bd9f3697d80d002ac5ea","56a0bd9f3697d80d002ac5eb","56b098a43a5b810d00745e3f","56b098da8f7a4f0d0029dd10","56d5a8ecf612b80b00fb69cd","570989853ab43c0e0072b2d6","571006aa10300c0e007f6133","5735a52431a73b1700887ca0","5744b0529e045c0e00b7a7a2","5744b1d0b56d431700d8a4fb","5744b1fb55d65a0e00b436e1","5744b218f9c7411700ce560e","5744b220f9c7411700ce560f","5744b2259e045c0e00b7a7a7","5744b22cf8b79f0e00de6a2d","5744b23155d65a0e00b436e4","5744b242c758290e00fbc235","5744b2569e045c0e00b7a7a8","5756a3f2bb92962900dafe3d","57ee23e81e42900e0014a42f","581c822c98676e0f00d240ef"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Sockets","version_clean":"1.1.0","version":"1.1"},"updates":["57618259a7c9f729009a74b6","5761b5e9b65324200072d799"],"next":{"pages":[],"description":""},"createdAt":"2015-02-18T00:03:59.824Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Chapter sections:\n1. [Overview](#overview)\n2. [Connecting with an Account Key](#connecting-with-an-account-key)\n3. [Connecting with an API Key ](#connecting-with-an-api-key)\n4. [Connecting with a User Key](#connecting-with-a-user-key)\n5. [Summary](#summary) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nIn this chapter you'll learn different methods of accessing the Syncano API. There are two ways of connecting to the Syncano API:\n\n1. With an Account Key\n2. With an API key\n\nEach of these methods have distinct use cases that you can read about in the sections below.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Connecting with an Account Key\"\n}\n[/block]\nBy using an Account Key you act as a Syncano Administrator. You can access almost every endpoint in the Syncano API (with [user endpoint](user-management#section-user-endpoint) being the only exception). What this means is that it can be used not only to create Users, Data Classes, Data Objects etc. but also to change your billing or account information. \n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"Because the Account Key has such strong permissions, we strongly advise you to use [API Keys](#connecting-with-an-api-key) in your application.\",\n  \"title\": \"Important!\"\n}\n[/block]\nWhat is also worth noting is that all the tasks (creating Instances, adding API Keys or billing info) that an Account Key is designed for, can be done from the [Syncano Dashboard](https://dashboard.syncano.io).\n\n## Getting an Account Key\nAn Account Key is created when you sign up for Syncano. An administrator can have only one Account Key and it can be reset in the event of an account being compromised. It cannot be deleted. You can get your Account Key from the Syncano Dashboard or by a call to the Syncano API.\n\n### Getting an Account Key via the Syncano Dashboard\nWhen logged in:\n1. Click on \"Account\" button in the top right corner\n2. Click on your name\n3. Go to \"Authentication\" tab\n4. Copy the Account Key \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/FkUjEOQTuGph0uGboCOq_Get_Account_Key.png\",\n        \"Get_Account_Key.png\",\n        \"1215\",\n        \"626\",\n        \"#233d64\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Getting an Account Key via an API Call\nYou can get the Account Key by making a call to `/account/auth/` endpoint:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n-H \\\"Content-type: application/json\\\" \\\\\\n-d '{\\\"email\\\":\\\"YOUR_EMAIL\\\", \\\"password\\\":\\\"YOUR_PASSWORD\\\"}' \\\\\\n\\\"https://api.syncano.io/v1.1/account/auth/\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"connection = syncano.connect(\\n    email='YOUR EMAIL',\\n    password='YOUR PASSWORD'\\n)\\n\\napi_key = connection.connection().authenticate_admin()\\n\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var Syncano = require('syncano');  // CommonJS\\nvar connection = Syncano();\\n\\nvar credentials = {\\n  email: YOUR_EMAIL, \\n  password: YOUR_PASSWORD\\n};\\n\\nconnection.Account.login(credentials).then(function(user) {\\n\\tconsole.log('user', user);\\n});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"// Not supported in Android Library\",\n      \"language\": \"java\",\n      \"name\": \"Android\"\n    },\n    {\n      \"code\": \"// Not supported in iOS Library\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"// Not supported in iOS Library\",\n      \"language\": \"objectivec\",\n      \"name\": \"Swift\"\n    },\n    {\n      \"code\": \"# Coming soon!\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"// Not supported in Unity Library\",\n      \"language\": \"csharp\",\n      \"name\": \"Unity\"\n    }\n  ]\n}\n[/block]\nIn the response you'll get your account details along with an Account Key:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"first_name\\\": \\\"Terry\\\",\\n    \\\"last_name\\\": \\\"Crews\\\",\\n    \\\"is_active\\\": true,\\n    \\\"account_key\\\": \\\"<ACCOUNT_KEY>\\\",\\n    \\\"id\\\": 64,\\n    \\\"has_password\\\": true,\\n    \\\"email\\\": \\\"flexing:::at:::pectorals.com\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Account Key connection\nOnce you have your Account Key, you can connect to the Syncano API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# In cURL, you have to pass API Key with every call you make, so e.g. to list all your instances, you can use\\n\\ncurl -X GET \\\\\\n-H \\\"X-API-KEY: <ACCOUNT_KEY>\\\" \\\\\\n\\\"https://api.syncano.io/v1.1/instances/\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"connection = syncano.connect(api_key=\\\"ACCOUNT_KEY\\\")\\n\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var connection = Syncano({accountKey: \\\"ACCOUNT_KEY\\\"});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"new SyncanoBuilder().apiKey(\\\"YOUR ACCOUNT KEY\\\").instanceName(\\\"YOUR INSTANCE\\\")\\n     .androidContext(context).setAsGlobalInstance(true).build();\",\n      \"language\": \"java\",\n      \"name\": \"Android\"\n    },\n    {\n      \"code\": \"Syncano *syncano = [Syncano sharedInstanceWithApiKey:@\\\"ACCOUNT KEY\\\" instanceName:@\\\"INSTANCE NAME\\\"];\\n\\n// on iOS it doesn't matter which key you use, you have to always specify an Instance you're connecting to\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"let syncano = Syncano.sharedInstanceWithApiKey(\\\"ACCOUNT KEY\\\", instanceName: \\\"INSTANCE NAME\\\")\\n  \\n//on iOS it doesn't matter which key you use, you have to always specify an Instance you're connecting to\",\n      \"language\": \"objectivec\",\n      \"name\": \"Swift\"\n    },\n    {\n      \"code\": \"api = Syncano.connect(api_key: \\\"<API_KEY>\\\")\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"syncano = SyncanoClient.Instance.Init(\\\"ACCOUNT_KEY\\\", \\\"INSTANCE_NAME\\\");\",\n      \"language\": \"csharp\",\n      \"name\": \"Unity\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Connecting with an API Key\"\n}\n[/block]\nYou can use an Account Key to perform different operations on your Syncano account, including edit it. \nAPI Keys have a different role. Their main purpose is to serve as an authentication method for an application that you intend to build **ON** Syncano. Because of that there are limitations in what can be achieved with the usage of an API Key. Here's a table that lists some of the major differences between Account Keys and API Keys:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Subject\",\n    \"h-1\": \"Account Key\",\n    \"h-2\": \"API Key\",\n    \"0-0\": \"Limit\",\n    \"0-1\": \"One Account Key per Administrator.\",\n    \"0-2\": \"No limit.\",\n    \"1-0\": \"Creation\",\n    \"1-1\": \"An Account key is created when an Administrator signs up for Syncano. It can be reset by an Administrator but cannot be deleted.\",\n    \"1-2\": \"Administrators can create/reset/delete API Keys.\",\n    \"2-0\": \"Permissions\",\n    \"2-1\": \"Full access to account, billing metrics data and every instance that an Administrator created. The only exception is a `/user/` endpoint (more on that in [User management](user-management) chapter )\",\n    \"2-2\": \"No access to account, billing or metrics data. Regular API Key can only view the data of an Instance that it was created in. It is possible to create/delete Data Objects with the API Key if proper [permissions](permissions) are configured.\",\n    \"3-0\": \"Scripts\",\n    \"3-1\": \"Can run/create/edit/delete/ Scripts\",\n    \"3-2\": \"No access to Scripts\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n ## Creating an API Key\nIf you'd like to connect to the Syncano API via an API Key, you should create it first. Again, you can do it either via the Syncano Dashboard or an API call:\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"API Key flags\",\n  \"body\": \"What is worth mentioning here is that API Keys can have three flags. Their usage is out of scope of this chapter so we are only giving a brief intro here:\\n- `ignore_acl` - API Key with this flag set to `true` will ignore permissions set for instance resources. You can read more about `ignore_acl` keys in the [Permissions](permissions#using-api-keys-and-user-keys) chapter.\\n- `allow_user_create` - API Key with this flag set to `true` can be used to create Users (it is not possible with a standard API Key). You can read more about User creation in the [User management](user-management#creating-an-api-key-with-user-creation-permissions) chapter.\\n- `allow_anonymous_read` - When this flag is set to `true` an API Key can read Data Classes and Data Objects with `other_permissions` set to `read` or higher. You can read more about this key in the [Permissions chapter](permissions#using-api-key-with-allow_anonymous_read-flag)\"\n}\n[/block]\n\n### Creating an API Key via the Syncano Dashboard\nTo add an API Key (while being in the instance menu):\n1. Click API Keys menu\n2. Click \"Add API Key button on the top right\n3. Add description\n4. Choose appropriate flags\n5. Click \"Confirm\" \n\nSee the screenshots below for details.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/VubnBe1aRGuoglNWHzUY_Add_API_Key_01.png\",\n        \"Add_API_Key_01.png\",\n        \"1279\",\n        \"656\",\n        \"#2e4c7a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/gOik1YibRJyZMGYrE9Uh_Add_API_Key_02.png\",\n        \"Add_API_Key_02.png\",\n        \"1279\",\n        \"656\",\n        \"#6c84a4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Creating an API Key via a call to the Syncano API\n\nThis is how you can create an API Key:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n-H \\\"X-API-KEY: ACCOUNT_KEY\\\" \\\\\\n\\\"https://api.syncano.io/v1.1/instances/instance_name/api_keys/\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"import syncano\\nfrom syncano.models import ApiKey\\n\\nsyncano.connect(api_key=\\\"API_KEY\\\")\\n\\napi_key_instance = ApiKey.please.create(instance_name=\\\"INSTANCE_NAME\\\")\\napi_key = api_key_instance.api_key\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var Syncano = require('syncano'); //CommonJS\\nvar connection = new Syncano({accountKey: \\\"ACCOUNT_KEY\\\"});\\nvar ApiKey = connection.ApiKey;\\n\\nApiKey.please().create({instanceName: 'INSTANCE_NAME'}).then(callback);\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"// Not supported in Android Library\",\n      \"language\": \"java\",\n      \"name\": \"Android\"\n    },\n    {\n      \"code\": \"// Not supported in iOS Library\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"// Not supported in iOS Library\",\n      \"language\": \"objectivec\",\n      \"name\": \"Swift\"\n    },\n    {\n      \"code\": \"api = Syncano.connect(api_key: \\\"<API_KEY>\\\")\\napi_key = api.api_keys.create\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"// Not supported in Unity Library\",\n      \"language\": \"csharp\",\n      \"name\": \"Unity\"\n    }\n  ]\n}\n[/block]\nExample response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"api_key\\\": \\\"<API_KEY>\\\",\\n    \\\"id\\\": 64,\\n    \\\"created_at\\\": \\\"2015-05-27T15:17:39.536805Z\\\",\\n    \\\"description\\\": \\\"\\\",\\n    \\\"ignore_acl\\\": false,\\n    \\\"allow_user_create\\\": false,\\n    \\\"allow_anonymous_read\\\": true,\\n    \\\"links\\\": {\\n        \\\"reset_key\\\": \\\"/v1.1/instances/<instance>/api_keys/64/reset_key/\\\",\\n        \\\"self\\\": \\\"/v1.1/instances/<instance>/api_keys/64/\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## API Key connection\nNow, when you have an API Key, you can connect to the Syncano API. You'll need to provide an `API Key` and an `instance name` in order to connect using this method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# In cURL, you have to pass API Key with every call you make, so e.g. to list instances associated with API Key, you can use\\n\\ncurl -X GET \\\\\\n-H \\\"X-API-KEY: <API_KEY>\\\" \\\\\\n\\\"https://api.syncano.io/v1.1/instances/\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"import syncano\\n\\nconnection = syncano.connect(\\n  instance_name='INSTANCE_NAME', \\n  api_key=\\\"API_KEY\\\")\\n\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var Syncano = require('syncano'); //CommonJS\\nvar connection = new Syncano({apiKey: \\\"API_KEY\\\"});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"new SyncanoBuilder().apiKey(\\\"YOUR API KEY\\\").instanceName(\\\"YOUR INSTANCE\\\")\\n     .androidContext(context).setAsGlobalInstance(true).build();\",\n      \"language\": \"java\",\n      \"name\": \"Android\"\n    },\n    {\n      \"code\": \"Syncano *syncano = [Syncano sharedInstanceWithApiKey:@\\\"API KEY\\\" instanceName:@\\\"INSTANCE NAME\\\"];\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"let syncano = Syncano.sharedInstanceWithApiKey(\\\"API KEY\\\", instanceName: \\\"INSTANCE NAME\\\")\",\n      \"language\": \"objectivec\",\n      \"name\": \"Swift\"\n    },\n    {\n      \"code\": \"api = Syncano.connect(api_key: \\\"MY_API_KEY\\\")\\ninstance = api.instances.find(\\\"myinstance\\\")\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"syncano = SyncanoClient.Instance.Init(\\\"API_KEY\\\", \\\"INSTANCE_NAME\\\");\",\n      \"language\": \"csharp\",\n      \"name\": \"Unity\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Connecting with a User Key\"\n}\n[/block]\n##GETTING A USER KEY\nA User Key is created when you add new User to your instance.\n\n###Getting an Account Key via the Syncano Dashboard\nWhen logged in:\n1. Choose desired instance\n2. Click on Users & Groups\n3. Click on Add a User button and add new user.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/60SDg60DTGmno2nYfKjP_2.png\",\n        \"2.png\",\n        3840,\n        1540,\n        \"#323232\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n4. Click on Show / Hide User Info and copy User Key\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/D0TUjF3QMSQjda3niEqh_1.png\",\n        \"1.png\",\n        3834,\n        1550,\n        \"#323232\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n##USER KEY CONNECTION\nYou can connect to the Syncano API using User Key. You'll need to provide specific User Key and an API Key.\n\n\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"`user_key` should be used along with `api_key` in all subsequent calls on the client side. So i.e. a call where a user is creating a Data Object would look like this:\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n-H \\\"X-API-KEY: API_KEY\\\" \\\\\\n-H \\\"X-USER-KEY: USER_KEY\\\" \\\\\\n-H \\\"Content-type: application/json\\\" \\\\\\n-d '{\\\"name\\\": \\\"I am an object name\\\"}' \\\\\\n\\\"https://api.syncano.io/v1.1/instances/instance_name/classes/class/objects/\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"cURL\"\n    },\n    {\n      \"code\": \"from syncano.models import Object\\nimport syncano\\n\\nsyncano.connect(\\n    api_key=\\\"API_KEY\\\",\\n    user_key=\\\"USER_KEY\\\",\\n    instance_name=\\\"INSTANCE_NAME\\\"\\n)\\n\\nObject.please.create(\\n    instance_name=\\\"INSTANCE_NAME\\\",\\n    class_name=\\\"CLASS_NAME\\\",\\n    name=\\\"I am a data object\\\"\\n)\",\n      \"language\": \"python\",\n      \"name\": \"Python\"\n    },\n    {\n      \"code\": \"var Syncano = require(\\\"syncano\\\");\\nvar connection = Syncano({apiKey: \\\"API_KEY\\\", userKey: \\\"USER_KEY\\\"});\\nvar DataObject = connection.DataObject;\\n\\nvar object = {\\n  instanceName: \\\"INSTANCE_NAME\\\", \\n  className: \\\"CLASS_NAME\\\",\\n  name: \\\"I am an object name\\\"\\n};\\n\\nDataObject.please().create(object).then(callback);\",\n      \"language\": \"javascript\",\n      \"name\": \"JavaScript\"\n    },\n    {\n      \"code\": \"syncano.setUserKey(userKey);\",\n      \"language\": \"java\",\n      \"name\": \"Android\"\n    },\n    {\n      \"code\": \"[Syncano sharedInstanceWithApiKey:@\\\"API_KEY\\\" instanceName:@\\\"instance_name\\\"];\\n[SCUser loginWithUsername:username password:password completion:^(NSError *error) {\\n  //handle error\\n}];\",\n      \"language\": \"objectivec\",\n      \"name\": \"Objective-C\"\n    },\n    {\n      \"code\": \"Syncano.sharedInstanceWithApiKey(\\\"API_KEY\\\", instanceName: \\\"instance_name\\\")\\nSCUser.loginWithUsername(\\\"username\\\", password: \\\"password\\\") { error in\\n  //handle error\\n}\",\n      \"language\": \"swift\",\n      \"name\": \"Swift\"\n    },\n    {\n      \"code\": \"# Coming soon!\",\n      \"language\": \"ruby\",\n      \"name\": \"Ruby\"\n    },\n    {\n      \"code\": \"syncano.UserKey = \\\"USER_KEY\\\";\",\n      \"language\": \"csharp\",\n      \"name\": \"Unity\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Summary\"\n}\n[/block]\nYou have learned about ways to connect to the Syncano API and how they are different from each other. You can now:\n- Go to the next chapter of the Developer Manual and learn about [Data Classes](classes) concept.\n- Check out the API Explorer for a more comprehensive list of [API Keys](http://docs.syncano.com/v0.1.1/docs/api-keys-list) and [Account](http://docs.syncano.com/v0.1.1/docs/account-details) methods","excerpt":"In this chapter you'll learn how to connect to the Syncano API with:\n- An Account Key\n- An API Key\n\nWe will also show what's the difference between Account Keys and API Keys.","slug":"authentication","type":"basic","title":"Authentication & API Keys"}

Authentication & API Keys

In this chapter you'll learn how to connect to the Syncano API with: - An Account Key - An API Key We will also show what's the difference between Account Keys and API Keys.

Chapter sections: 1. [Overview](#overview) 2. [Connecting with an Account Key](#connecting-with-an-account-key) 3. [Connecting with an API Key ](#connecting-with-an-api-key) 4. [Connecting with a User Key](#connecting-with-a-user-key) 5. [Summary](#summary) [block:api-header] { "type": "basic", "title": "Overview" } [/block] In this chapter you'll learn different methods of accessing the Syncano API. There are two ways of connecting to the Syncano API: 1. With an Account Key 2. With an API key Each of these methods have distinct use cases that you can read about in the sections below. [block:api-header] { "type": "basic", "title": "Connecting with an Account Key" } [/block] By using an Account Key you act as a Syncano Administrator. You can access almost every endpoint in the Syncano API (with [user endpoint](user-management#section-user-endpoint) being the only exception). What this means is that it can be used not only to create Users, Data Classes, Data Objects etc. but also to change your billing or account information. [block:callout] { "type": "danger", "body": "Because the Account Key has such strong permissions, we strongly advise you to use [API Keys](#connecting-with-an-api-key) in your application.", "title": "Important!" } [/block] What is also worth noting is that all the tasks (creating Instances, adding API Keys or billing info) that an Account Key is designed for, can be done from the [Syncano Dashboard](https://dashboard.syncano.io). ## Getting an Account Key An Account Key is created when you sign up for Syncano. An administrator can have only one Account Key and it can be reset in the event of an account being compromised. It cannot be deleted. You can get your Account Key from the Syncano Dashboard or by a call to the Syncano API. ### Getting an Account Key via the Syncano Dashboard When logged in: 1. Click on "Account" button in the top right corner 2. Click on your name 3. Go to "Authentication" tab 4. Copy the Account Key [block:image] { "images": [ { "image": [ "https://files.readme.io/FkUjEOQTuGph0uGboCOq_Get_Account_Key.png", "Get_Account_Key.png", "1215", "626", "#233d64", "" ] } ] } [/block] ### Getting an Account Key via an API Call You can get the Account Key by making a call to `/account/auth/` endpoint: [block:code] { "codes": [ { "code": "curl -X POST \\\n-H \"Content-type: application/json\" \\\n-d '{\"email\":\"YOUR_EMAIL\", \"password\":\"YOUR_PASSWORD\"}' \\\n\"https://api.syncano.io/v1.1/account/auth/\"", "language": "curl" }, { "code": "connection = syncano.connect(\n email='YOUR EMAIL',\n password='YOUR PASSWORD'\n)\n\napi_key = connection.connection().authenticate_admin()\n", "language": "python" }, { "code": "var Syncano = require('syncano'); // CommonJS\nvar connection = Syncano();\n\nvar credentials = {\n email: YOUR_EMAIL, \n password: YOUR_PASSWORD\n};\n\nconnection.Account.login(credentials).then(function(user) {\n\tconsole.log('user', user);\n});", "language": "javascript" }, { "code": "// Not supported in Android Library", "language": "java", "name": "Android" }, { "code": "// Not supported in iOS Library", "language": "objectivec" }, { "code": "// Not supported in iOS Library", "language": "objectivec", "name": "Swift" }, { "code": "# Coming soon!", "language": "ruby" }, { "code": "// Not supported in Unity Library", "language": "csharp", "name": "Unity" } ] } [/block] In the response you'll get your account details along with an Account Key: [block:code] { "codes": [ { "code": "{\n \"first_name\": \"Terry\",\n \"last_name\": \"Crews\",\n \"is_active\": true,\n \"account_key\": \"<ACCOUNT_KEY>\",\n \"id\": 64,\n \"has_password\": true,\n \"email\": \"flexing@pectorals.com\"\n}", "language": "json" } ] } [/block] ## Account Key connection Once you have your Account Key, you can connect to the Syncano API: [block:code] { "codes": [ { "code": "# In cURL, you have to pass API Key with every call you make, so e.g. to list all your instances, you can use\n\ncurl -X GET \\\n-H \"X-API-KEY: <ACCOUNT_KEY>\" \\\n\"https://api.syncano.io/v1.1/instances/\"", "language": "curl" }, { "code": "connection = syncano.connect(api_key=\"ACCOUNT_KEY\")\n", "language": "python" }, { "code": "var connection = Syncano({accountKey: \"ACCOUNT_KEY\"});", "language": "javascript" }, { "code": "new SyncanoBuilder().apiKey(\"YOUR ACCOUNT KEY\").instanceName(\"YOUR INSTANCE\")\n .androidContext(context).setAsGlobalInstance(true).build();", "language": "java", "name": "Android" }, { "code": "Syncano *syncano = [Syncano sharedInstanceWithApiKey:@\"ACCOUNT KEY\" instanceName:@\"INSTANCE NAME\"];\n\n// on iOS it doesn't matter which key you use, you have to always specify an Instance you're connecting to", "language": "objectivec" }, { "code": "let syncano = Syncano.sharedInstanceWithApiKey(\"ACCOUNT KEY\", instanceName: \"INSTANCE NAME\")\n \n//on iOS it doesn't matter which key you use, you have to always specify an Instance you're connecting to", "language": "objectivec", "name": "Swift" }, { "code": "api = Syncano.connect(api_key: \"<API_KEY>\")", "language": "ruby" }, { "code": "syncano = SyncanoClient.Instance.Init(\"ACCOUNT_KEY\", \"INSTANCE_NAME\");", "language": "csharp", "name": "Unity" } ] } [/block] [block:api-header] { "type": "basic", "title": "Connecting with an API Key" } [/block] You can use an Account Key to perform different operations on your Syncano account, including edit it. API Keys have a different role. Their main purpose is to serve as an authentication method for an application that you intend to build **ON** Syncano. Because of that there are limitations in what can be achieved with the usage of an API Key. Here's a table that lists some of the major differences between Account Keys and API Keys: [block:parameters] { "data": { "h-0": "Subject", "h-1": "Account Key", "h-2": "API Key", "0-0": "Limit", "0-1": "One Account Key per Administrator.", "0-2": "No limit.", "1-0": "Creation", "1-1": "An Account key is created when an Administrator signs up for Syncano. It can be reset by an Administrator but cannot be deleted.", "1-2": "Administrators can create/reset/delete API Keys.", "2-0": "Permissions", "2-1": "Full access to account, billing metrics data and every instance that an Administrator created. The only exception is a `/user/` endpoint (more on that in [User management](user-management) chapter )", "2-2": "No access to account, billing or metrics data. Regular API Key can only view the data of an Instance that it was created in. It is possible to create/delete Data Objects with the API Key if proper [permissions](permissions) are configured.", "3-0": "Scripts", "3-1": "Can run/create/edit/delete/ Scripts", "3-2": "No access to Scripts" }, "cols": 3, "rows": 4 } [/block] ## Creating an API Key If you'd like to connect to the Syncano API via an API Key, you should create it first. Again, you can do it either via the Syncano Dashboard or an API call: [block:callout] { "type": "info", "title": "API Key flags", "body": "What is worth mentioning here is that API Keys can have three flags. Their usage is out of scope of this chapter so we are only giving a brief intro here:\n- `ignore_acl` - API Key with this flag set to `true` will ignore permissions set for instance resources. You can read more about `ignore_acl` keys in the [Permissions](permissions#using-api-keys-and-user-keys) chapter.\n- `allow_user_create` - API Key with this flag set to `true` can be used to create Users (it is not possible with a standard API Key). You can read more about User creation in the [User management](user-management#creating-an-api-key-with-user-creation-permissions) chapter.\n- `allow_anonymous_read` - When this flag is set to `true` an API Key can read Data Classes and Data Objects with `other_permissions` set to `read` or higher. You can read more about this key in the [Permissions chapter](permissions#using-api-key-with-allow_anonymous_read-flag)" } [/block] ### Creating an API Key via the Syncano Dashboard To add an API Key (while being in the instance menu): 1. Click API Keys menu 2. Click "Add API Key button on the top right 3. Add description 4. Choose appropriate flags 5. Click "Confirm" See the screenshots below for details. [block:image] { "images": [ { "image": [ "https://files.readme.io/VubnBe1aRGuoglNWHzUY_Add_API_Key_01.png", "Add_API_Key_01.png", "1279", "656", "#2e4c7a", "" ] } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/gOik1YibRJyZMGYrE9Uh_Add_API_Key_02.png", "Add_API_Key_02.png", "1279", "656", "#6c84a4", "" ] } ] } [/block] ### Creating an API Key via a call to the Syncano API This is how you can create an API Key: [block:code] { "codes": [ { "code": "curl -X POST \\\n-H \"X-API-KEY: ACCOUNT_KEY\" \\\n\"https://api.syncano.io/v1.1/instances/instance_name/api_keys/\"", "language": "curl" }, { "code": "import syncano\nfrom syncano.models import ApiKey\n\nsyncano.connect(api_key=\"API_KEY\")\n\napi_key_instance = ApiKey.please.create(instance_name=\"INSTANCE_NAME\")\napi_key = api_key_instance.api_key", "language": "python" }, { "code": "var Syncano = require('syncano'); //CommonJS\nvar connection = new Syncano({accountKey: \"ACCOUNT_KEY\"});\nvar ApiKey = connection.ApiKey;\n\nApiKey.please().create({instanceName: 'INSTANCE_NAME'}).then(callback);", "language": "javascript" }, { "code": "// Not supported in Android Library", "language": "java", "name": "Android" }, { "code": "// Not supported in iOS Library", "language": "objectivec" }, { "code": "// Not supported in iOS Library", "language": "objectivec", "name": "Swift" }, { "code": "api = Syncano.connect(api_key: \"<API_KEY>\")\napi_key = api.api_keys.create", "language": "ruby" }, { "code": "// Not supported in Unity Library", "language": "csharp", "name": "Unity" } ] } [/block] Example response: [block:code] { "codes": [ { "code": "{\n \"api_key\": \"<API_KEY>\",\n \"id\": 64,\n \"created_at\": \"2015-05-27T15:17:39.536805Z\",\n \"description\": \"\",\n \"ignore_acl\": false,\n \"allow_user_create\": false,\n \"allow_anonymous_read\": true,\n \"links\": {\n \"reset_key\": \"/v1.1/instances/<instance>/api_keys/64/reset_key/\",\n \"self\": \"/v1.1/instances/<instance>/api_keys/64/\"\n }\n}", "language": "json" } ] } [/block] ## API Key connection Now, when you have an API Key, you can connect to the Syncano API. You'll need to provide an `API Key` and an `instance name` in order to connect using this method: [block:code] { "codes": [ { "code": "# In cURL, you have to pass API Key with every call you make, so e.g. to list instances associated with API Key, you can use\n\ncurl -X GET \\\n-H \"X-API-KEY: <API_KEY>\" \\\n\"https://api.syncano.io/v1.1/instances/\"", "language": "curl" }, { "code": "import syncano\n\nconnection = syncano.connect(\n instance_name='INSTANCE_NAME', \n api_key=\"API_KEY\")\n", "language": "python" }, { "code": "var Syncano = require('syncano'); //CommonJS\nvar connection = new Syncano({apiKey: \"API_KEY\"});", "language": "javascript" }, { "code": "new SyncanoBuilder().apiKey(\"YOUR API KEY\").instanceName(\"YOUR INSTANCE\")\n .androidContext(context).setAsGlobalInstance(true).build();", "language": "java", "name": "Android" }, { "code": "Syncano *syncano = [Syncano sharedInstanceWithApiKey:@\"API KEY\" instanceName:@\"INSTANCE NAME\"];", "language": "objectivec" }, { "code": "let syncano = Syncano.sharedInstanceWithApiKey(\"API KEY\", instanceName: \"INSTANCE NAME\")", "language": "objectivec", "name": "Swift" }, { "code": "api = Syncano.connect(api_key: \"MY_API_KEY\")\ninstance = api.instances.find(\"myinstance\")", "language": "ruby" }, { "code": "syncano = SyncanoClient.Instance.Init(\"API_KEY\", \"INSTANCE_NAME\");", "language": "csharp", "name": "Unity" } ] } [/block] [block:api-header] { "type": "basic", "title": "Connecting with a User Key" } [/block] ##GETTING A USER KEY A User Key is created when you add new User to your instance. ###Getting an Account Key via the Syncano Dashboard When logged in: 1. Choose desired instance 2. Click on Users & Groups 3. Click on Add a User button and add new user. [block:image] { "images": [ { "image": [ "https://files.readme.io/60SDg60DTGmno2nYfKjP_2.png", "2.png", 3840, 1540, "#323232", "" ] } ] } [/block] 4. Click on Show / Hide User Info and copy User Key [block:image] { "images": [ { "image": [ "https://files.readme.io/D0TUjF3QMSQjda3niEqh_1.png", "1.png", 3834, 1550, "#323232", "" ] } ] } [/block] ##USER KEY CONNECTION You can connect to the Syncano API using User Key. You'll need to provide specific User Key and an API Key. [block:callout] { "type": "success", "body": "`user_key` should be used along with `api_key` in all subsequent calls on the client side. So i.e. a call where a user is creating a Data Object would look like this:" } [/block] [block:code] { "codes": [ { "code": "curl -X POST \\\n-H \"X-API-KEY: API_KEY\" \\\n-H \"X-USER-KEY: USER_KEY\" \\\n-H \"Content-type: application/json\" \\\n-d '{\"name\": \"I am an object name\"}' \\\n\"https://api.syncano.io/v1.1/instances/instance_name/classes/class/objects/\"", "language": "curl", "name": "cURL" }, { "code": "from syncano.models import Object\nimport syncano\n\nsyncano.connect(\n api_key=\"API_KEY\",\n user_key=\"USER_KEY\",\n instance_name=\"INSTANCE_NAME\"\n)\n\nObject.please.create(\n instance_name=\"INSTANCE_NAME\",\n class_name=\"CLASS_NAME\",\n name=\"I am a data object\"\n)", "language": "python", "name": "Python" }, { "code": "var Syncano = require(\"syncano\");\nvar connection = Syncano({apiKey: \"API_KEY\", userKey: \"USER_KEY\"});\nvar DataObject = connection.DataObject;\n\nvar object = {\n instanceName: \"INSTANCE_NAME\", \n className: \"CLASS_NAME\",\n name: \"I am an object name\"\n};\n\nDataObject.please().create(object).then(callback);", "language": "javascript", "name": "JavaScript" }, { "code": "syncano.setUserKey(userKey);", "language": "java", "name": "Android" }, { "code": "[Syncano sharedInstanceWithApiKey:@\"API_KEY\" instanceName:@\"instance_name\"];\n[SCUser loginWithUsername:username password:password completion:^(NSError *error) {\n //handle error\n}];", "language": "objectivec", "name": "Objective-C" }, { "code": "Syncano.sharedInstanceWithApiKey(\"API_KEY\", instanceName: \"instance_name\")\nSCUser.loginWithUsername(\"username\", password: \"password\") { error in\n //handle error\n}", "language": "swift", "name": "Swift" }, { "code": "# Coming soon!", "language": "ruby", "name": "Ruby" }, { "code": "syncano.UserKey = \"USER_KEY\";", "language": "csharp", "name": "Unity" } ] } [/block] [block:api-header] { "type": "basic", "title": "Summary" } [/block] You have learned about ways to connect to the Syncano API and how they are different from each other. You can now: - Go to the next chapter of the Developer Manual and learn about [Data Classes](classes) concept. - Check out the API Explorer for a more comprehensive list of [API Keys](http://docs.syncano.com/v0.1.1/docs/api-keys-list) and [Account](http://docs.syncano.com/v0.1.1/docs/account-details) methods