# Company Level Authentication

Company is a top-level principal within the Turium Enigma platform and you would be able to obtain an access token and a refresh token on a Company’s behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received. 

### Obtaining an auth token <a href="#obtain_token" id="obtain_token"></a>

To begin the authentication flow for a company, one must first obtain a temporary auth token through administrator.&#x20;

Auth tokens are valid only for 24 hours. 24 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 24 hours in case of network failure.

```
POST /profile-service/v1/keys/principals/<companyId>/authtoken/
```

```
200 OK
```

```
{
  "status": "PASS",
  "code": 0,
  "errormsg": "",
  "token": "<authToken>"
}
```

**Redirects User to Client’s auth handler URI (Connect URL) and passing in the authToken**

```
301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid
```

At this point, the user should be prompted to sign in to your application. If the user doesn’t not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms.&#x20;

**Client app calls Oauth2 password grant to get an access token for the company**

<table data-full-width="true"><thead><tr><th>Name</th><th>Type</th><th>Format</th><th>Description</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>string</code></td><td><code>UIID</code></td><td>Applications client_id supplied by App Management</td></tr><tr><td><code>client_secret</code></td><td><code>string</code></td><td><code>UUID</code></td><td>Applications client_secret supplied by App Management</td></tr><tr><td><code>grant_type</code></td><td><code>string</code></td><td>-</td><td>Specify which grant type you expect the oauth2 service to process. For password grant, the value is <code>password</code></td></tr><tr><td><code>username</code></td><td><code>string</code></td><td>-</td><td>specify the <code>companyId</code> to be used in the password grant request. The <code>id</code> above.</td></tr><tr><td><code>password</code></td><td><code>string</code></td><td>-</td><td>specify the <code>authToken</code> to be used in the password grant request. The <code>requestToken</code> above.</td></tr><tr><td><code>credtype</code></td><td><code>string</code></td><td>-</td><td>The credtype signifies to oauth2 which credential set is being submitted in the request. The value: <code>authtoken</code>.</td></tr></tbody></table>

### Example <a href="#example" id="example"></a>

#### Request <a href="#request" id="request"></a>

```
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Connection: close
Content-Length: 175

client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken
```

#### Response <a href="#response" id="response"></a>

**Success**

```
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
```

```
{
  "expires_in": "3600",
  "scope": "app_scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token"
}
```

**Failure**

```
{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}
```

### Response Codes <a href="#response_codes" id="response_codes"></a>

**HTTP Status Code returned by oauth2**

<table data-full-width="true"><thead><tr><th>HTTP Status Code</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>OK - Successful call, response is in body.</td></tr><tr><td>400</td><td>Bad Request <code>(error, error_description, code)</code></td></tr><tr><td>401</td><td>Unauthorized <code>(error, error_description, code)</code></td></tr><tr><td>403</td><td>Forbidden <code>(error, error_description, code)</code></td></tr><tr><td>404</td><td>Not Found <code>(error, error_description, code)</code></td></tr><tr><td>500</td><td>Server Error, error message is in body.</td></tr><tr><td>503</td><td>Server Timed Out, error message is in body.</td></tr></tbody></table>

4xx class errors have a JSON response with the following fields

```
{
  "code": "<number>",
  "error": "<error>",
  "error_description": "<error_description>"
}
```

**/token**

<table data-full-width="true"><thead><tr><th>Code</th><th>Error</th><th>Description</th></tr></thead><tbody><tr><td>5</td><td><code>invalid_grant</code></td><td>Incorrect credentials. Please Retry</td></tr><tr><td>10</td><td><code>invalid_grant</code></td><td>Account is disabled. Please contact support</td></tr><tr><td>11</td><td><code>invalid_grant</code></td><td>Account is disabled. Please contact support</td></tr><tr><td>12</td><td><code>invalid_grant</code></td><td>Logon Denied. Please contact support</td></tr><tr><td>13</td><td><code>invalid_grant</code></td><td>Logon Denied. Please contact support</td></tr><tr><td>14</td><td><code>invalid_grant</code></td><td>Account Locked. Please contact support</td></tr><tr><td>16</td><td><code>invalid_request</code></td><td>user lives elsewhere</td></tr><tr><td>19</td><td><code>invalid_grant</code></td><td>Incorrect credentials. Please Retry</td></tr><tr><td>20</td><td><code>invalid_grant</code></td><td>Logon Denied. Please contact support (typically due to IP restriction)</td></tr><tr><td>51</td><td><code>invalid_request</code></td><td>username was not supplied</td></tr><tr><td>52</td><td><code>invalid_request</code></td><td>password was not supplied</td></tr><tr><td>53</td><td><code>invalid_client</code></td><td>company is not enabled for this client</td></tr><tr><td>54</td><td><code>invalid_scope</code></td><td>requested scope exceeds granted scope</td></tr><tr><td>55</td><td><code>invalid_request</code></td><td>we don’t know this email</td></tr><tr><td>56</td><td><code>invalid_request</code></td><td><code>otp</code> was not supplied</td></tr><tr><td>57</td><td><code>invalid_request</code></td><td><code>channel_type</code> missing</td></tr><tr><td>58</td><td><code>invalid_request</code></td><td><code>channel_handle</code> missing</td></tr><tr><td>59</td><td><code>access_denied</code></td><td>client disabled</td></tr><tr><td>60</td><td><code>invalid_grant</code></td><td>these are not the grants you are looking for</td></tr><tr><td>61</td><td><code>invalid_client</code></td><td>client not found</td></tr><tr><td>62</td><td><code>invalid_request</code></td><td><code>client_id</code> was not supplied</td></tr><tr><td>63</td><td><code>invalid_request</code></td><td><code>client_secret</code> was not supplied</td></tr><tr><td>64</td><td><code>invalid_client</code></td><td>Incorrect credentials. Please Retry</td></tr><tr><td>65</td><td><code>invalid_request</code></td><td><code>grant_type</code> was not supplied</td></tr><tr><td>80</td><td><code>invalid_request</code></td><td>invalid channel type</td></tr><tr><td>81</td><td><code>invalid_request</code></td><td>bad channel handle</td></tr><tr><td>83</td><td><code>invalid_request</code></td><td>otp not found</td></tr><tr><td>84</td><td><code>invalid_request</code></td><td>fact verification failed</td></tr><tr><td>85</td><td><code>invalid_request</code></td><td>otp verification failed</td></tr><tr><td>100</td><td><code>invalid_request</code></td><td>backend does not know about this username</td></tr><tr><td>101</td><td><code>invalid_request</code></td><td>code was not supplied</td></tr><tr><td>102</td><td><code>invalid_request</code></td><td><code>redirect_uri</code> was not supplied</td></tr><tr><td>103</td><td><code>invalid_request</code></td><td>code is bad or expired</td></tr><tr><td>104</td><td><code>invalid_grant</code></td><td><code>redirect_uri</code> does not match the previous grant</td></tr><tr><td>105</td><td><code>invalid_grant</code></td><td>this grant was not issued to you!</td></tr><tr><td>106</td><td><code>invalid_request</code></td><td><code>refresh_token</code> was not supplied</td></tr><tr><td>107</td><td><code>invalid_request</code></td><td>refresh disallowed for app</td></tr><tr><td>108</td><td><code>invalid_grant</code></td><td>bad or expired refresh token</td></tr><tr><td>109</td><td><code>invalid_request</code></td><td><code>loginid</code> was not supplied</td></tr><tr><td>115</td><td><code>invalid_request</code></td><td>unauthenticated client will not be issued token!</td></tr><tr><td>117</td><td><code>invalid_request</code></td><td>nonce is mandatory for this <code>response_type</code></td></tr><tr><td>118</td><td><code>invalid_request</code></td><td>display is invalid</td></tr><tr><td>119</td><td><code>invalid_request</code></td><td>prompt is invalid</td></tr><tr><td>119</td><td><code>invalid_request</code></td><td>prompt must be set to consent for <code>offline_access</code></td></tr><tr><td>120</td><td><code>invalid_request</code></td><td><code>credtype</code> is invalid</td></tr><tr><td>121</td><td><code>invalid_request</code></td><td><code>login_type</code> is invalid</td></tr><tr><td>122</td><td><code>invalid_request</code></td><td>proxies supplied are invalid</td></tr><tr><td>123</td><td><code>invalid_request</code></td><td>principal is disabled</td></tr><tr><td>134</td><td><code>invalid_request</code></td><td>Company undergoing scheduled maintenance.</td></tr></tbody></table>