{"_id":"56d1f33b00a2a70b00b365d5","category":{"_id":"56d1f33900a2a70b00b36592","project":"5526c95cf69851170038b48f","version":"56d1f33700a2a70b00b3658e","pages":["56d1f33b00a2a70b00b365d3","56d1f33b00a2a70b00b365d4","56d1f33b00a2a70b00b365d5","56d1f33b00a2a70b00b365d6","56d1f33b00a2a70b00b365d7","56d1f33b00a2a70b00b365d8","56d1f33b00a2a70b00b365d9","56d1f33b00a2a70b00b365da","56d1f33b00a2a70b00b365db","56d1f33b00a2a70b00b365dc","56d5984cf612b80b00fb6997"],"__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T15:43:12.697Z","from_sync":false,"order":2,"slug":"ionic-user","title":"Ionic User"},"project":"5526c95cf69851170038b48f","user":"5526ca4cf69851170038b496","version":{"_id":"56d1f33700a2a70b00b3658e","project":"5526c95cf69851170038b48f","__v":2,"createdAt":"2016-02-27T19:04:23.946Z","releaseDate":"2016-02-27T19:04:23.946Z","categories":["56d1f33900a2a70b00b3658f","56d1f33900a2a70b00b36590","56d1f33900a2a70b00b36591","56d1f33900a2a70b00b36592","56d1f33900a2a70b00b36593","56d1f33900a2a70b00b36594","56d1f33900a2a70b00b36595","56d1f33900a2a70b00b36596","56d1f33900a2a70b00b36597","56d1f33900a2a70b00b36598","56d1f33900a2a70b00b36599","56d1f33900a2a70b00b3659a","571f9497ada30c34003b7cee"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta","version_clean":"2.0.0-beta","version":"2.0.0-beta"},"parentDoc":null,"__v":2,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-03T14:27:05.197Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Users can be created using [basic](#basic-user-signup) authentication, [custom](doc:custom-authentication) authentication, or by using a [social provider](doc:social-providers) integration. No matter which method you choose, each user is assigned a universally unique identifier ([UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)) and tied directly to the application in which it was registered.\n\n* [Registering](#section-registration) a User.\n  * Gather more [data](#section-gathering-more-data)\n  * Handle [registration errors](#section-handling-registration-errors)\n* [Authenticate](#section-authenticate-users) a User.\n* [Basic Example](#section-basic-example)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"\"\n}\n[/block]\n## Registration\n\nThis will introduce you to creating users with our basic authentication. If you already have an existing set of authenticated users in another system, you should check out our [Custom Authentication](doc:custom-authentication) docs or have a look at the [Social Providers](doc:social-providers) integrations we offer.\n\nBasic authentication requires an e-mail and password to login, so we will need to register a user with a minimum of those details. You can *optionally* have them choose a username, but it is not a necessary for registration or login.\n\nYou register users using the `Ionic.Auth.signup` method, which takes a registration object, and returns a Promise:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var details = {\\n  'email': 'email:::at:::example.com',\\n  'password': 'secret'\\n}\\n\\n// optionally pass a username\\n// details.username = 'ionitron';\\n\\nIonic.Auth.signup(details).then(signupSuccess, signupFailure);\",\n      \"language\": \"javascript\",\n      \"name\": \"example:\"\n    }\n  ]\n}\n[/block]\nE-mail must be unique to the app. The same is true of username if it is used. If all goes correctly, a new user will be created and the promise resolution handler will be called.\n\nYou can now safely authenticate the user. \n\n\n#### Gathering more data\n\nIf you need to register a user with more details, you can pass a JSON object as part of the signup details. Each field passed in the custom object is directly tied to a Users custom data, so you can pull back these details later on.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var details = {\\n  'email': 'email@example.com',\\n  'password': 'secret'\\n}\\n\\n// optionally passed custom data\\ndetails.custom = {\\n\\t'wants_emails': true,\\n  'favoriteColor': 'blue',\\n  'website': 'http://ionic.io'\\n};\\n\\nIonic.Auth.signup(details).then(signupSuccess, signupFailure);\",\n      \"language\": \"javascript\",\n      \"name\": \"example:\"\n    }\n  ]\n}\n[/block]\n#### Handling Registration Errors\n\nIf the signup is not successful, signupFailure will be called with a single argument. The argument will be an array of error strings that you can use to trigger an appropriate action in your application.\n\nError Codes:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Error\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`required_email`\",\n    \"0-1\": \"Missing E-mail field\",\n    \"1-0\": \"`required_password`\",\n    \"1-1\": \"Missing Password field\",\n    \"2-0\": \"`conflict_email`\",\n    \"2-1\": \"A User has already signed up with the supplied `e-mail`.\",\n    \"3-0\": \"`conflict_username`\",\n    \"3-1\": \"A User has already signed up with the supplied `username`.\",\n    \"4-0\": \"`invalid_email`\",\n    \"4-1\": \"The e-mail did not pass validation.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Authenticate Users\n\nOnce you have a registered user or configured a social provider integration, authenticating a user is quite simple:\n\n```javascript\nIonic.Auth.login(provider, settings, data).then(success, failure);\n```\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"provider\",\n    \"h-0\": \"Variable\",\n    \"h-1\": \"Type\",\n    \"0-1\": \"String\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"Name of the login provider\",\n    \"1-0\": \"settings\",\n    \"1-1\": \"Object\",\n    \"h-3\": \"Accepted Values\",\n    \"0-3\": \"`basic`, `facebook`, `github`, `google`, `instagram`, `linkedin`, `twitter`\",\n    \"1-2\": \"Authentication settings. The only attribute currently allowed is `remember` which determines whether or not the user will stay logged in.\",\n    \"1-3\": \"{\\n  \\\"remember\\\": true\\n}\",\n    \"2-0\": \"data\",\n    \"2-1\": \"Object\",\n    \"2-2\": \"Additional data that a provider may need to authenticate.\",\n    \"2-3\": \"Basic auth requires an object with an `email` and `password` defined.\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\nIf the user successfully authenticates, the promise will call the `success` handler, otherwise the `failure` handler will be called.\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n## Basic Example\n\nHere is an example of how to use basic authentication to authenticate a User:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var authProvider = 'basic';\\nvar authSettings = { 'remember': true };\\n\\nvar loginDetails = {\\n  'email': 'user@example.com',\\n  'password': 'secret'\\n};\\n\\nvar authSuccess = function(user) {\\n  // user was authenticated, you can get the authenticated user\\n  // with Ionic.User.current();\\n};\\n\\nvar authFailure = function(errors) {\\n  for (var err in errors) {\\n   \\t// check the error and provide an appropriate message\\n    // for your application\\n  }\\n};\\n\\nvar login = function() {\\n  Ionic.Auth.login(authProvider, authSettings, loginDetails)\\n    .then(authSuccess, authFailure);\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"Javascript\"\n    },\n    {\n      \"code\": \".controller('LoginCtrl', function($scope, $state) {\\n\\n  var authProvider = 'basic';\\n\\tvar authSettings = { 'remember': true };\\n\\n\\tvar loginDetails = {\\n \\t\\t'email': 'user@example.com',\\n  \\t'password': 'secret'\\n\\t};\\n\\n  $scope.authSuccess = function() {\\n    // replace dash with the name of your main state\\n    $state.go('dash'); \\n  };\\n\\n  $scope.authFailure = function(errors) {\\n    for (var err in errors) {\\n   \\t\\t// check the error and provide an appropriate message\\n    \\t// for your application\\n  \\t}\\n  };\\n\\n  $scope.login = function(provider) {\\n    Ionic.Auth.login(authProvider, authSettings, loginDetails)\\n      .then(authSuccess, authFailure);\\n  };\\n})\",\n      \"language\": \"javascript\",\n      \"name\": \"AngularJS\"\n    }\n  ]\n}\n[/block]","excerpt":"Learn how to Register and Authenticate your application users","slug":"user-authentication","type":"basic","title":"Authentication"}

Authentication

Learn how to Register and Authenticate your application users

Users can be created using [basic](#basic-user-signup) authentication, [custom](doc:custom-authentication) authentication, or by using a [social provider](doc:social-providers) integration. No matter which method you choose, each user is assigned a universally unique identifier ([UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)) and tied directly to the application in which it was registered. * [Registering](#section-registration) a User. * Gather more [data](#section-gathering-more-data) * Handle [registration errors](#section-handling-registration-errors) * [Authenticate](#section-authenticate-users) a User. * [Basic Example](#section-basic-example) [block:api-header] { "type": "basic", "title": "" } [/block] ## Registration This will introduce you to creating users with our basic authentication. If you already have an existing set of authenticated users in another system, you should check out our [Custom Authentication](doc:custom-authentication) docs or have a look at the [Social Providers](doc:social-providers) integrations we offer. Basic authentication requires an e-mail and password to login, so we will need to register a user with a minimum of those details. You can *optionally* have them choose a username, but it is not a necessary for registration or login. You register users using the `Ionic.Auth.signup` method, which takes a registration object, and returns a Promise: [block:code] { "codes": [ { "code": "var details = {\n 'email': 'email@example.com',\n 'password': 'secret'\n}\n\n// optionally pass a username\n// details.username = 'ionitron';\n\nIonic.Auth.signup(details).then(signupSuccess, signupFailure);", "language": "javascript", "name": "example:" } ] } [/block] E-mail must be unique to the app. The same is true of username if it is used. If all goes correctly, a new user will be created and the promise resolution handler will be called. You can now safely authenticate the user. #### Gathering more data If you need to register a user with more details, you can pass a JSON object as part of the signup details. Each field passed in the custom object is directly tied to a Users custom data, so you can pull back these details later on. [block:code] { "codes": [ { "code": "var details = {\n 'email': 'email@example.com',\n 'password': 'secret'\n}\n\n// optionally passed custom data\ndetails.custom = {\n\t'wants_emails': true,\n 'favoriteColor': 'blue',\n 'website': 'http://ionic.io'\n};\n\nIonic.Auth.signup(details).then(signupSuccess, signupFailure);", "language": "javascript", "name": "example:" } ] } [/block] #### Handling Registration Errors If the signup is not successful, signupFailure will be called with a single argument. The argument will be an array of error strings that you can use to trigger an appropriate action in your application. Error Codes: [block:parameters] { "data": { "h-0": "Error", "h-1": "Description", "0-0": "`required_email`", "0-1": "Missing E-mail field", "1-0": "`required_password`", "1-1": "Missing Password field", "2-0": "`conflict_email`", "2-1": "A User has already signed up with the supplied `e-mail`.", "3-0": "`conflict_username`", "3-1": "A User has already signed up with the supplied `username`.", "4-0": "`invalid_email`", "4-1": "The e-mail did not pass validation." }, "cols": 2, "rows": 5 } [/block] [block:api-header] { "type": "basic" } [/block] ## Authenticate Users Once you have a registered user or configured a social provider integration, authenticating a user is quite simple: ```javascript Ionic.Auth.login(provider, settings, data).then(success, failure); ``` [block:parameters] { "data": { "0-0": "provider", "h-0": "Variable", "h-1": "Type", "0-1": "String", "h-2": "Description", "0-2": "Name of the login provider", "1-0": "settings", "1-1": "Object", "h-3": "Accepted Values", "0-3": "`basic`, `facebook`, `github`, `google`, `instagram`, `linkedin`, `twitter`", "1-2": "Authentication settings. The only attribute currently allowed is `remember` which determines whether or not the user will stay logged in.", "1-3": "{\n \"remember\": true\n}", "2-0": "data", "2-1": "Object", "2-2": "Additional data that a provider may need to authenticate.", "2-3": "Basic auth requires an object with an `email` and `password` defined." }, "cols": 4, "rows": 3 } [/block] If the user successfully authenticates, the promise will call the `success` handler, otherwise the `failure` handler will be called. [block:api-header] { "type": "basic" } [/block] ## Basic Example Here is an example of how to use basic authentication to authenticate a User: [block:code] { "codes": [ { "code": "var authProvider = 'basic';\nvar authSettings = { 'remember': true };\n\nvar loginDetails = {\n 'email': 'user@example.com',\n 'password': 'secret'\n};\n\nvar authSuccess = function(user) {\n // user was authenticated, you can get the authenticated user\n // with Ionic.User.current();\n};\n\nvar authFailure = function(errors) {\n for (var err in errors) {\n \t// check the error and provide an appropriate message\n // for your application\n }\n};\n\nvar login = function() {\n Ionic.Auth.login(authProvider, authSettings, loginDetails)\n .then(authSuccess, authFailure);\n};", "language": "javascript", "name": "Javascript" }, { "code": ".controller('LoginCtrl', function($scope, $state) {\n\n var authProvider = 'basic';\n\tvar authSettings = { 'remember': true };\n\n\tvar loginDetails = {\n \t\t'email': 'user@example.com',\n \t'password': 'secret'\n\t};\n\n $scope.authSuccess = function() {\n // replace dash with the name of your main state\n $state.go('dash'); \n };\n\n $scope.authFailure = function(errors) {\n for (var err in errors) {\n \t\t// check the error and provide an appropriate message\n \t// for your application\n \t}\n };\n\n $scope.login = function(provider) {\n Ionic.Auth.login(authProvider, authSettings, loginDetails)\n .then(authSuccess, authFailure);\n };\n})", "language": "javascript", "name": "AngularJS" } ] } [/block]