You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/device-manufacturer-guidance/building-a-seam-compatible-smart-lock-api/implementing-authentication.md
A Seam integration starts with a user linking their account to your platform. We prefer [OAuth2](https://oauth.net/2/) because it provides a standardized, secure way to authenticate users and issue long-lived tokens while ensuring Seam never needs direct access to a user’s private credentials. A clean OAuth2 implementation is the foundation for a stable, reliable integration.
9
+
A Seam integration starts when a user signs in to their device provider and gives your platform permission to access their account. The easiest way to support this is through [OAuth2](https://oauth.net/2/), because it gives users a familiar login screen and lets your API issue secure, long-lasting tokens without exposing passwords.
10
10
11
11
***
12
12
13
13
## OAuth2 with Access + Refresh Tokens
14
14
15
15
Your API should use the standard [OAuth2 Authorization Code flow](https://oauth.net/2/).
16
16
17
-
#### Authorization Request Example
17
+
### 1. Authorization request launches the flow
18
+
19
+
As the first step, Seam makes a GET request to your authorization URL. This should show the user a login screen from your service.
@@ -34,7 +38,63 @@ GET https://api.provider.com/oauth/authorize?
34
38
35
39
***
36
40
37
-
#### OAuth Callback Example
41
+
### 2. User login + consent screen
42
+
43
+
After Seam sends the authorization request in [step 1](implementing-authentication.md#id-1.-authorization-request-launches-the-flow), your service should display a login and consent screen. The user signs in, reviews what Seam will be able to access, and decides whether to continue.
44
+
45
+
46
+
47
+
{% columns %}
48
+
{% column %}
49
+
<figure><imgsrc="../../.gitbook/assets/google sign in copy.png"alt=""width="375"><figcaption><p>Example login screen from Google</p></figcaption></figure>
50
+
51
+
52
+
{% endcolumn %}
53
+
54
+
{% column %}
55
+
<figure><imgsrc="../../.gitbook/assets/image (48).png"alt=""width="375"><figcaption><p>Example consent screen from Google</p></figcaption></figure>
56
+
57
+
58
+
{% endcolumn %}
59
+
{% endcolumns %}
60
+
61
+
Your UI should:
62
+
63
+
* ask the user to log in
64
+
* clearly show what Seam will access
65
+
* allow them to approve or deny
66
+
67
+
This step should feel identical to signing into your own product.
68
+
69
+
***
70
+
71
+
### 3. Redirect back to Seam with a code
72
+
73
+
After approval, redirect the browser back to the provided redirect URL:
74
+
75
+
```
76
+
https://example.com/oauth_redirect
77
+
```
78
+
79
+
Your service must append the authorization code (`code`) and `state`:
80
+
81
+
```http
82
+
https://example.com/oauth_redirect?
83
+
code=abc123_code_from_provider&
84
+
state=xyz123
85
+
```
86
+
87
+
**Key expectations:**
88
+
89
+
* the redirect URL must exactly match one that Seam registered with your platform.
90
+
*`code` is the temporary value Seam will exchange for tokens.
91
+
*`state` must match what Seam originally sent in [Step 1](implementing-authentication.md#id-1.-authorization-request-launches-the-flow).
92
+
93
+
***
94
+
95
+
### 4. Exchange the code for tokens
96
+
97
+
Seam will exchange the authorization code for tokens:
38
98
39
99
```http
40
100
POST https://api.provider.com/oauth/token
@@ -47,9 +107,7 @@ client_id=seam_prod_123&
47
107
client_secret=shhh_very_secret
48
108
```
49
109
50
-
#### Token Response Example
51
-
52
-
Your API should return both `access_token`, `refresh_token`, and a stable user or account ID:
110
+
**Expected response:**
53
111
54
112
```json
55
113
{
@@ -61,17 +119,17 @@ Your API should return both `access_token`, `refresh_token`, and a stable user o
61
119
}
62
120
```
63
121
64
-
**Requirements:**
122
+
**Best practices:**
65
123
66
124
*`access_token` expires quickly (`1h` is typical)
67
125
*`refresh_token` lasts long and is stable
68
126
*`user_id` must be stable across all future authentications
69
127
70
128
***
71
129
72
-
### Use of Bearer Tokens
130
+
### 5. Calling your API with the access token
73
131
74
-
Seam can call your APIs using the standard `Authorization` header:
132
+
Seam can call your APIs using the access token. A common way is to do it using the the standard `Authorization` header:
| User connects account | Returns `user_id = provider_user_491829`|
152
-
| User disconnects | No change |
153
-
| User reconnects later | Returns the same `user_id = provider_user_491829`|
154
-
155
-
If it changes, Seam must treat it as a new account — which breaks reconnect flows.
156
-
157
196
***
158
197
159
198
### Multiple Redirect URLs
160
199
161
-
Your OAuth app should allow Seam to register multiple redirect URIs.
200
+
Seam generally likes to use separate redirect URIs for production, staging, and local development. It's preferable if your provider allows registering multiple URLs.
0 commit comments