> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://ocient.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ocient.ferndocs.com/_mcp/server.

# Request an OpenID device grant code

POST /v1/sso_device_grant
Content-Type: application/json

Get an OpenID device grant code that can be verified and
subsequently used on an /sso\_device\_grant\_verify request.

The device grant flow is designed for devices that have limited input capabilities
or no web browser. It works as follows:

1. Call this endpoint to get a user code and verification URI
2. Display the user code and verification URI to the user
3. The user visits the verification URI on another device and enters the code
4. Call the /sso\_device\_grant\_verify endpoint to check if the user has completed verification

### Example

```bash
curl -X POST https://your-ocient-instance/v1/sso_device_grant \
  -H "Content-Type: application/json" \
  -d '{
    "database": "retail_analytics"
  }'
```

Reference: https://ocient.ferndocs.com/api-reference/sso-integration/ssodevicegrant

## Request

### Body (application/json)

This endpoint expects a SSODeviceGrantRequest.

- `database` (string, optional) — Target database name (defaults to system if not specified). This is the database the user will be connected to after completing the device grant flow.

## Response

### 200

Token exchange successful

- `status` (Status, required)
- `verification_uri_complete` (string, optional) — A complete URI that includes the verification code, which the user can visit directly to complete the authentication.
- `verification_uri` (string, optional) — The base URI where the user needs to go to enter the code manually.
- `user_code` (string, optional) — The code that should be displayed to the user, to be entered at the verification_uri. This is typically a short, easy-to-type code.

## Errors

### 401 Unauthorized Error

Unauthorized

- `status` (Status, required)

## Types

### Status

- `reason` (string, required) — Human-readable description of the operation result
- `sql_state` (string, required) — SQL state code (see Error Handling section for common codes)
- `vendor_code` (integer, required) — Vendor-specific error code

## Examples

### Device Grant Response

**Response**

```json
{
  "status": {
    "reason": "Device authorization initiated",
    "sql_state": "00000",
    "vendor_code": 0
  },
  "verification_uri_complete": "https://auth.example.com/device?code=BCDFGHJK",
  "verification_uri": "https://auth.example.com/device",
  "user_code": "BCDFGHJK"
}
```

**SDK Code**

```python Device Grant Response
import requests

url = "https://v1/sso_device_grant"

response = requests.post(url)

print(response.json())
```

```javascript Device Grant Response
const url = 'https://v1/sso_device_grant';
const options = {method: 'POST'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Device Grant Response
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://v1/sso_device_grant"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Device Grant Response
require 'uri'
require 'net/http'

url = URI("https://v1/sso_device_grant")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
```

```java Device Grant Response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://v1/sso_device_grant")
  .asString();
```

```php Device Grant Response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://v1/sso_device_grant');

echo $response->getBody();
```

```csharp Device Grant Response
using RestSharp;

var client = new RestClient("https://v1/sso_device_grant");
var request = new RestRequest(Method.POST);
IRestResponse response = client.Execute(request);
```

```swift Device Grant Response
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://v1/sso_device_grant")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Device Grant Request

**Request**

```json
{
  "database": "retail_analytics"
}
```

**Response**

```json
{
  "status": {
    "reason": "Device authorization initiated",
    "sql_state": "00000",
    "vendor_code": 0
  },
  "verification_uri_complete": "https://auth.example.com/device?code=BCDFGHJK",
  "verification_uri": "https://auth.example.com/device",
  "user_code": "BCDFGHJK"
}
```

**SDK Code**

```python Device Grant Request
import requests

url = "https://v1/sso_device_grant"

payload = { "database": "retail_analytics" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Device Grant Request
const url = 'https://v1/sso_device_grant';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"database":"retail_analytics"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Device Grant Request
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://v1/sso_device_grant"

	payload := strings.NewReader("{\n  \"database\": \"retail_analytics\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Device Grant Request
require 'uri'
require 'net/http'

url = URI("https://v1/sso_device_grant")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"database\": \"retail_analytics\"\n}"

response = http.request(request)
puts response.read_body
```

```java Device Grant Request
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://v1/sso_device_grant")
  .header("Content-Type", "application/json")
  .body("{\n  \"database\": \"retail_analytics\"\n}")
  .asString();
```

```php Device Grant Request
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://v1/sso_device_grant', [
  'body' => '{
  "database": "retail_analytics"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Device Grant Request
using RestSharp;

var client = new RestClient("https://v1/sso_device_grant");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"database\": \"retail_analytics\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Device Grant Request
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["database": "retail_analytics"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://v1/sso_device_grant")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```