{"_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"}

Getting Started

Security Profiles

Ionic User

Ionic Push

Ionic Deploy

Ionic Analytics

Ionic Package

API

Ionic View

Debugging

Support

Addons

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]