{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"da03ee56-5026-472f-93e2-30592520338a","name":"Odin API","description":"Welcome to Odin API\n\n# Access Tokens\n\nODiN API uses JSON Web Tokens to authenticate API requests.\n\n## Access Token Request\n\nTo request an access token, you must POST to the Session endpoint, with a payload containing the username, password, and encryption type of the user you wish to login with.\n\nThe encryption type is only applicable to versions prior to R22. R22 and above **must** use plain passwords.\n\nThe encryption type defaults to plain and may be ommitted. If you wish to encrypt the password, you may encrypt it with SHA1 and set the encryption type to \"sha1\".\n\nIn multi-cluster mode the XSP address is automatically associated with a particular hostname of your API endpoint. eg: cluster1.mydomain.com vs cluster2.mydomain.com.\n\nHowever, you may also explicitly request a particular XSP address by sending the xsp parameter in the Access Token Request.\n\n#### Create an sha1 password from shell\n\n``` bash\n$ echo -n 'My Password' | shasum -\n933257a3349a248d1e0fb19d7c953a00ff004a1d -\n$ echo -n 'My Password' | openssl dgst -sha1\n933257a3349a248d1e0fb19d7c953a00ff004a1d\n\n ```\n\n#### Example HTTP POST\n\n``` http\nPOST /api/v2/auth/token HTTP/1.1\nHost: odinapi.net\nContent-Type: application/json\n{ \"username\": \"myusername\", \"password\": \"plainpassword\" }\n\n ```\n\n#### Example HTTP POST with Encryption\n\n``` http\nPOST /api/v2/auth/token HTTP/1.1\nHost: odinapi.net\nContent-Type: application/json\n{ \"username\": \"myusername\", \"password\": \"hash\", \"encryption\": \"sha1\" }\n\n ```\n\n#### Example HTTP POST with XSP\n\n``` http\nPOST /api/v2/auth/token HTTP/1.1\nHost: odinapi.net\nContent-Type: application/json\n{ \"username\": \"myusername\", \"password\": \"plain\", \"xsp\": \"prefix://myxsp.com:port\" }\n\n ```\n\n## Access Token Response\n\n### Successful Responses\n\nA successful response from the Access Token Request contain a **200** status code with a JSON payload containing the Access Token.\n\n#### Example Successful Response\n\n``` http\nHTTP/1.1 200 OK\nDate: Sun, 04 Dec 2016 20:10:14 GMT\nContent-Length: 1571\nContent-Type: application/json\nConnection: close\n{ \"token\": \"TOKEN\" }\n\n ```\n\n### Error Responses\n\nError Responses will contain a **40x** status code and a message that describes what the error was.\n\nPossible Errors are:\n\n- 401: Invalid Parameters\n- 402: Password Expired\n- 403: Invalid Credentials\n    \n\n#### Example Error Response\n\n``` http\nHTTP/1.1 403 Forbidden\nDate: Sun, 04 Dec 2016 20:33:20 GMT\nContent-Length: 65\nContent-Type: application/json\nConnection: close\n{ \"error\": \"[Error 4962] Invalid password\", \"status\": 403, \"path\": \"api/v2/auth/token\", \"details\": \"ODIN API Error\" }\n\n ```\n\n# API Requests\n\nThe Access Token that is returned from this operation MUST be used on most\\* API requests as a Bearer Token in an Authorization header.\n\n\\*Access Tokens are not required to obtain a token or to check the status of the application.\n\n**NOTE**:\n\nThe Authorization header will contain two words Bearer followed by a space followed by the Access Token. Below we are using TOKEN as an example, although the real token will be much longer.\n\n### Example API Request\n\n``` http\nGET /api/v2/users?userId=someuser@somedomain.com HTTP/1.1\nHost: odinapi.net\nContent-Type: application/json\nAuthorization: Bearer TOKEN\nConnection: close\n\n ```\n\n### Example API Flow\n\n#### Obtain a token\n\n```\ncurl --request POST \\\n  --url 'https://odinapi.net/api/v2/auth/token' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"username\": \"MYUSER\", \"password\": \"MYPASS\", \"encryption\": \"plain\"}'\n{\n  \"token\": \"THISISANEXAMPLETOKEN\"\n}\n\n ```\n\n#### Use that token\n\n```\ncurl --request GET \\\n  --url 'https://odinapi.net/api/v2/service-providers' \\\n  --header 'Authorization: Bearer THISISANEXAMPLETOKEN'\n[\n  {\n    \"serviceProviderId\": \"odin.mock.ent1\",\n    \"serviceProviderName\": \"Odin Mock Enterprise 1\",\n    \"isEnterprise\": true\n  },\n  {\n    \"serviceProviderId\": \"odin.mock.sp1\",\n    \"serviceProviderName\": \"Odin Mock Service Provider 1\",\n    \"isEnterprise\": false\n  }\n]\n\n ```\n\n## Token Expiration\n\nBy default all tokens are _expendable_ and expire after 24 hours. You may re-use a token before the expiration. There are several options you have to handle token expiration.\n\n### Request a new token each time.\n\nYou may prefix a command or a batch of commands with a token request and add the returned token to the headers for each API call in that batch.\n\n### Inspect the expiration time\n\nYou may use a JWT library ([https://jwt.io/](https://jwt.io/)) to inspect the expiration time of the current token. If the token has or is about to expire, then request a new token before sending an API call.\n\n### Intercept authentication errors\n\nWhen a token is expired, you will receive a 401 error with a message indicating so. You may choose to intercept authentication errors and if the conditions show the token is expired, obtain a new token, and then retry the request.  \neg:\n\n```\n{\n    \"error\": \"Expired token\",\n    \"status\": 401,\n    \"path\": \"api/v2/service-providers\",\n    \"details\": \"ODIN API Error\"\n}\n\n ```\n\n# Successful Responses\n\nSuccessful API responses will contain a **20x** status code and a JSON payload.\n\n#### Example Successful API Response\n\n``` http\nHTTP/1.1 200 OK\nDate: Sun, 04 Dec 2016 20:10:15 GMT\nContent-Length: 429\nContent-Type: application/json\nConnection: close\n{ \"status\": \"ok\" }\n\n ```\n\n# Error Responses\n\nError responses will contain a **40x** status code and a JSON payload describing the error.\n\nSome potential Error responses are:\n\n- 400: Invalid Parameters\n- 401: Token Required\n- 402: Password Expired\n- 403: Login Failed\n- 404: Not Found\n    \n\n#### Example Error Response\n\n``` http\nHTTP/1.1 404 Not Found\nDate: Sun, 04 Dec 2016 20:33:20 GMT\nContent-Length: 194\nContent-Type: application/json\nConnection: close\n{ \"error\": \"[Error 4505] Access Device not found: invalid-device\", \"status\": 404,\"path\": \"api/v2/service-providers/devices?serviceProviderId=somesp&groupId=somegrp&deviceName=invalid-device\", \"details\": \"ODIN API Error\" }\n\n ```\n\n# SSO\n\nODiN Portal offers single sign-on utilizing the JWT tokens that were described in the Access Tokens section. The 3rd party that is accessing ODiN must have the username and password of the user.\n\nThe steps are as follows:\n\n- Obtain an access token using the Authentication method\n- Redirect the user to /app/#!/sso?token=xxx, appending the token in a query parameter\n    \n\n#### Example\n\nThe following example is using curl and the open command available in OSX terminal.\n\n``` bash\nURL='https://demo.odinapi.net'\nUSER=username\nPASS=password\nJSON=\"{\\\"username\\\": \\\"$USER\\\", \\\"password\\\": \\\"$PASS\\\"}\"\nRESP=`curl -s -f -H \"Accept: application/json\" -H \"Content-Type: application/json\" -d \"$JSON\" ${URL}/api/v2/auth/token`\nTOKEN=`echo \"$RESP\" | awk -F':' '{print $2}' | sed 's/}$//g' | sed 's/^\"//g' | sed 's/\"$//g'`\nopen \"$URL/app/#!/sso?token=${TOKEN}\"\n\n ```\n\n**NOTE** :\n\n- r = required\n- o = optional\n- n = nullable **example :** __ { \"description\" : \"\" }","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"427160","collectionId":"da03ee56-5026-472f-93e2-30592520338a","publishedId":"RWTsrFXj","public":true,"publicUrl":"https://doc.odinapi.net","privateUrl":"https://go.postman.co/documentation/427160-da03ee56-5026-472f-93e2-30592520338a","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.4","publishDate":"2020-06-25T12:26:19.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://odinapi.net/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://doc.odinapi.net/view/metadata/RWTsrFXj"}