قوسىمشالار ٴۇشىن OAuth ۲.۰

OAuth ۲.۰ قوسىمشاعا پايدالانۋشى اتىنان Planfix-كە پارول سۇراماي نەمەسە ساقتاماي قول جەتكىزۋگە مۇمكىندىك بەرەدى.

Planfix مىندەتتى تۇردە PKCE S۲۵۶ قولدانىلاتىن Authorization Code اعىنىن (flow) پايدالانادى. OAuth ارقىلى REST API نەمەسە Planfix MCP سەرۆەرى-گە قوسىلۋعا بولادى.

دايىن AI كلىييەنتىن قوسقىڭىز كەلسە، الدىمەن Planfix MCP پاراعىنا قاراڭىز. ەگەر كىرۋدى ٴوز ەسەپ جازباڭىزدا باسقاراتىن بولساڭىز، OAuth and MCP applications in an account پاراعىنا ٴوتىڭىز. پارتنەرلەر مەن كوپەسەپتىك ىينتەگراتسىييالاردى جاساۋشىلارعا OAuth applications for partners پايدالى بولادى.

قوسىمشانى تىركەۋدىڭ وپتسىييالارى

وپتسىييا	قاشان قولدانۋ قاجەت	قاي جەردە جۇمىس ىستەيدى
ەسەپتىك جازباعا تىييەسىلى قوسىمشا	ىينتەگراتسىييا ٴبىر ەسەپتىك جازباعا ارنالعان جانە كلىييەنتكە الدىن الا انىقتالعان `client_id` قاجەت.	تەك ونى تىركەگەن ەسەپتىك جازبادا.
سەرىكتەسكە تىييەسىلى قوسىمشا	بىردەي قوسىمشا بىرنەشە كلىييەنتتىك ەسەپتىك جازبالارعا قوسىلۋى كەرەك.	قاۋىپسىزدىك ساياساتى نەمەسە اكىمشى رۇقسات ەتكەن ەسەپتىك جازبالاردا.
اۆتوماتتى MCP كلىييەنتىن تىركەۋ	MCP كلىييەنتى Client ID Metadata Document (CIMD) نەمەسە Dynamic Client Registration (DCR) قولدايدى.	تىركەۋ وزىمەن بىرگە ەسەپتىك جازباعا قولجەتىمدىلىك بەرمەيدى. قوسىمشا ٴالى دە تاڭدالعان ەسەپتىك جازبادا رۇقسات ەتىلۋى ٴتىيىس.

CIMD جانە DCR تەك MCP قوسىلىمدارى ٴۇشىن قولجەتىمدى. REST API ٴۇشىن ەسەپتىك جازباعا تىييەسىلى نەمەسە سەرىكتەسكە تىييەسىلى قوسىمشانى پايدالانىڭىز.

OAuth سوڭعى نۇكتەلەرى (endpoints)

جاڭا ىينتەگراتسىييالار عالامدىق (global) سوڭعى نۇكتەلەردى پايدالانۋى كەرەك. وسى URL-دەرگە ەسەپتىك جازبا اتاۋى ەندىرىلمەيدى: پايدالانۋشى اۆتورىيزاتسىييا كەزىندە ەسەپتىك جازبانى تاڭدايدى.

ماقسات	ادرەس
Issuer	`https://auth.planfix.com`
Authorization	`https://auth.planfix.com/oauth/authorize`
Token	`https://auth.planfix.com/oauth/token`
User information	`https://auth.planfix.com/oauth/userinfo`
Token revocation	`https://auth.planfix.com/oauth/revoke`
Dynamic MCP client registration	`https://auth.planfix.com/oauth/register`

اۆتورىيزاتسىييا سەرۆەرىنىڭ مەتادەرەكتەرى ستاندارتتى سوڭعى نۇكتەلەردە قولجەتىمدى:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

Redirect URI-لار

Redirect URI قوسىمشا پارامەترلەرىندە تىركەلۋى ٴتىيىس. اۆتورىيزاتسىييا سۇراۋىندا جىبەرىلگەن ٴمان تىركەلگەن URI-عا سايكەس بولۋى كەرەك.

رۇقسات ەتىلگەندەر:

https URL-دارى؛
http URL-دارى تەك loopback حوستتار (مىسالى، localhost نەمەسە 127.0.0.1) ٴۇشىن عانا.

Loopback URI-دە پورت دىينامىيكالىق بولۋى مۇمكىن، بىراق سحەماسى، حوستى، جولى جانە سۇرانىس (query) سايكەس بولۋى ٴتىيىس. URL فراگمەنتتەرى جانە URL ىشىندەگى پايدالانۋشى تۋرالى اقپاراتقا رۇقسات جوق.

قولجەتىمدىلىك دەڭگەيلەرى

قوسىمشا الدىن الا رۇقسات ەتىلگەن قولجەتىمدىلىك دەڭگەيلەرى نەمەسە scopes عانا الادى. تولىق ٴتىزىم ٴۇشىن REST API access levels قاراڭىز.

سۇرالعان جىيىنتىق قوسىمشاعا تىركەلگەن scope-تاردىڭ كومەسكىسى (subset) بولۋى ٴتىيىس. قوسىمشا scope-تارى Planfix ىشىندەگى پايدالانۋشىنىڭ رۇقساتتارىن كەڭەيتپەيدى: قوسىمشا تەك قوسقان قىزمەتكەرگە قولجەتىمدى دەرەكتەرگە عانا قول جەتكىزە الادى.

باسقارىلاتىن قوسىمشالارعا قوسىمشا قىزمەتتىك scope-تار userinfo، openid، جانە email بەرىلەدى.

پايدالانۋشى اۆتورىيزاتسىيياسى

code_verifier جانە ونىڭ SHA-۲۵۶ تۇرلەندىرىلۋى code_challenge قۇرىڭىز، سودان كەيىن اۆتورىيزاتسىييا سوڭعى نۇكتەسىن براۋزەردە اشىڭىز.

REST API مىسالى:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

MCP ٴۇشىن ٴدال MCP سەرۆەرىنىڭ URL-ٴىن كورسەتەتىن resource پارامەترىن قوسىڭىز:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

پارامەتر	سىيپاتتاماسى
`client_id`	تىركەلگەن قوسىمشانىڭ ىيدەنتىيفىيكاتورى. CIMD ٴۇشىن بۇل كلىييەنت مەتادەرەكتەر قۇجاتىنىڭ URL-ٴى.
`redirect_uri`	رۇقسات ەتىلگەن Redirect URI-لاردىڭ ٴبىرى.
`response_type`	`code` بولۋى قاجەت.
`scope`	بوس ورنىمەن بولىنگەن قاجەتتى رۇقساتتار. بۇل پارامەتر REST API ٴۇشىن مىندەتتى. MCP كلىييەنتى ونى جىبەرمەۋى مۇمكىن — ونداي جاعدايدا قوسىمشاعا رۇقسات ەتىلگەن scope-تار قولدانىلادى.
`state`	سۇراۋدى الماستىرۋدان قورعاۋ ٴۇشىن كەزدەيسوق ٴمان. قايتا باعىتتالعاننان كەيىن قوسىمشا ونى تەكسەرۋى ٴتىيىس.
`code_challenge`	`code_verifier`-ٴدىڭ SHA-۲۵۶ حەشىنىڭ padding-سىز base۶۴url ٴتۇرى.
`code_challenge_method`	تەك `S256` قولداۋ كورسەتىلەدى.
`resource`	MCP ٴۇشىن ٴدال URL `https://mcp.planfix.com/mcp`. REST API ٴۇشىن بۇل پارامەتردى جىبەرمەڭىز.

پايدالانۋشى ەسەپتىك جازبانى تاڭداپ، جۇيەگە كىرەدى جانە سۇرالعان رۇقساتتاردى قارايدى. ەسەپتىك جازباعا تىييەسىلى قوسىمشا تىكەلەي ٴوزىنىڭ ىييەلىك ەتەتىن ەسەپتىك جازباسىن اشادى. ەگەر قاۋىپسىزدىك ساياساتى اكىمشى ماقۇلداۋىن تالاپ ەتسە، Planfix ٴتىيىستى قادامدى كورسەتەدى. اكىمشى قوسىمشانى ماقۇلداپ، ونى ٴبىر ارەكەتپەن قوسۋى مۇمكىن.

تابىستى اۆتورىيزاتسىييادان كەيىن Planfix براۋزەردى redirect_uri-گە قايتا باعىتتايدى:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

اۆتورىيزاتسىييا كودى ٴبىر رەتتىك جانە ۱۰ مىينۋت ىشىندە جارامدى.

توكەن الۋ

/oauth/token-كە POST سۇراۋىن application/x-www-form-urlencoded تۇرىندە جىبەرىڭىز:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

MCP ٴۇشىن اۆتورىيزاتسىييا سۇراۋىندا قولدانىلعانمەن ٴدال سول resource پارامەترىن قايتالاڭىز.

پابلىيك (public) كلىييەنت سۇراۋدى سەكرەتسىز جىبەرەدى. كونفىيدەنتسىيالدى (confidential) كلىييەنت client_secret_basic ارقىلى نەمەسە سۇراۋ دەنەسىندە client_id جانە client_secret پارامەترلەرىمەن اۋتەنتىيفىيكاتسىييالانادى.

مىسال جاۋاپ:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

REST API ٴۇشىن جاۋاپتا قوسىمشا account_name، account_domain، جانە account_url بولادى. وسى ماندەردى ساقتاپ، REST API سۇراۋلارىندا تاڭدالعان ەسەپتىك جازبانىڭ URL-ٴىن پايدالانىڭىز.

Access token ۲۴ ساعاتقا جارامدى. ول پايدالانۋشىعا، ەسەپتىك جازباعا، قوسىمشاعا، scope-تارعا جانە resource-قا بايلانىستى. MCP ٴۇشىن بەرىلگەن توكەن تىكەلەي REST API-دە قولدانىلمايدى، جانە REST API ٴۇشىن بەرىلگەن توكەن MCP-دە قولدانىلمايدى.

REST API-مەن توكەندى پايدالانۋ

توكەندى Authorization تاقىرىبىندا جىبەرىڭىز:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

توكەن الماستىرۋ كەزىندە authorization code-تى ايىرباستاۋ كەزىندە قايتارىلعان ەسەپتىك جازبا URL-ٴىن قولدانىڭىز. تەك رۇقسات ەتىلگەن scope-تارمەن قامتىلعان ادىستەرگە قولجەتىمدىلىك بار. OAuth توكەندەرى ەسەپتىك جازبا جوسپارىنا جانە ستاندارتتى REST API limits شەكتەۋلەرىنە باعىنادى.

پايدالانۋشى تۋرالى اقپارات

userinfo سۇراۋى openid scope-ىن تالاپ ەتەدى:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

email scope-ى بار كەزدە مىسال جاۋاپ:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

عالامدىق OAuth اۆتورىيزاتسىيياسى ەسەپتىك جازبانىڭ قىزمەتكەرلەرى ٴۇشىن قولجەتىمدى. Planfix id_token شىعارمايدى؛ پايدالانۋشى دەرەكتەرىن الۋ ٴۇشىن userinfo-دى سۇراڭىز.

توكەندەردى جاڭارتۋ

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

MCP ٴۇشىن ٴدال سول resource ٴمانىن جىبەرىڭىز. كونفىيدەنتسىيالدى كلىييەنت ٴوز سەكرەتىمەن اۋتەنتىيفىيكاتسىييالانۋى ٴتىيىس.

Planfix جاڭا access token جانە جاڭا refresh token قايتارادى. الدىڭعى refresh token دەرەۋ جارامسىز بولادى، سوندىقتان قوسىمشا ساقتالعان ٴماندى اتومارلى تۇردە الماستىرۋى ٴتىيىس.

توكەندى قايتارۋ (revoke)

كلىييەنت refresh token-دى /oauth/revoke ارقىلى قايتارىپ تاستاي الادى:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

پايدالانۋشى ٴوز بايلانىسىن ٴوزىنىڭ پايدالانۋشى كارتاسىنداعى Session management بولىمىنەن دە وشىرە الادى. اكىمشى ٴۇشىنشى تاراپ قوسىمشاسىنىڭ ماقۇلداۋىن بۇكىل ەسەپتىك جازبا ٴۇشىن قايتارۋى مۇمكىن. OAuth and MCP applications in an account قاراڭىز.

بار ىينتەگراتسىييالارمەن ۇيلەسىمدىلىگى

https://account.planfix.com/api/v2/oauth/authorize، /token، جانە /userinfo سىيياقتى تەنانت (tenant) سوڭعى نۇكتەلەرى ناقتى ەسەپتىك جازباعا بايلانعان بۇرىننان بار ىينتەگراتسىييالار ٴۇشىن جۇمىسىن جالعاستىرادى.

جاڭا ىينتەگراتسىييالار ٴۇشىن عالامدىق سوڭعى نۇكتەلەردى پايدالانىڭىز. ولار ستاندارتتى مەتادەرەكتەردى تابۋدى، ەسەپتىك جازبانى تاڭداۋدى جانە MCP-ٴنى قولدايدى. ٴبىر OAuth سەانسىنا عالامدىق جانە تەنانت سوڭعى نۇكتەلەرىن ارالاستىرىپ قولدانباڭىز.

قاۋىپسىزدىك بويىنشا ۇسىنىستار

ارقاشان PKCE S۲۵۶ قولدانىڭىز جانە state-ٴتى تەكسەرىڭىز.
ٴموبىيلدى، دەسكتوپ جانە براۋزەر قوسىمشالارى ٴۇشىن سەكرەتسىز (public) كلىييەنت پايدالانىڭىز.
سەكرەت سەرۆەردە سەنىمدى تۇردە ساقتالاتىن كەزدە عانا كونفىيدەنتسىيالدى كلىييەنتتى پايدالانىڭىز.
قاجەت مىينىيمۋم scope-تاردى سۇراڭىز.
Access token-داردى، refresh token-داردى، authorization code-تاردى، code_verifier-ٴدى نەمەسە كلىييەنت سەكرەتتەرىن جۋرنالدارعا جازباڭىز.
Refresh token-دار مەن كلىييەنت سەكرەتتەرىن شىيفرلانعان ساقتاۋ ورنىندا ساقتاڭىز.
جاۋاپتاعى iss-ٴتى تەكسەرىڭىز جانە تەك كۇتىلگەن Planfix issuer-ٴىن عانا قابىلداڭىز.

مۇمكىن قاتەلەر

قاتە	سەبەبى
`invalid_client`	كلىييەنت بەلگىسىز نەمەسە وشىرىلگەن، كلىييەنت سەكرەتى دۇرىس ەمەس، نەمەسە قوسىمشا تاڭدالعان ەسەپتىك جازبادا قولجەتىمدى ەمەس.
`invalid_grant`	اۆتورىيزاتسىييا كودى نەمەسە refresh token جارامسىز، مەرزىمى وتكەن، بۇرىن قولدانىلعان، نەمەسە كلىييەنتكە، redirect URI-گە، PKCE دەرەكتەرىنە نەمەسە resource-قا سايكەس كەلمەيدى.
`invalid_scope`	سۇراۋ قوسىمشاعا رۇقسات ەتىلمەگەن scope-تى قامتىيدى.
`invalid_target`	`resource` قولداۋ كورسەتىلمەيدى نەمەسە سۇراۋلار اراسىندا وزگەرگەن.
`access_denied`	پايدالانۋشى قوسىلۋدان باس تارتتى نەمەسە ەسەپتىك جازبا ساياساتى قوسىمشانى رۇقسات ەتپەيدى.
HTTP ۴۰۱، `invalid_token`	Access token بەلگىسىز، مەرزىمى وتكەن نەمەسە قايتارىلعان.
HTTP ۴۰۳، `insufficient_scope`	وپەراتسىييا ٴۇشىن قاجەت scope توكەندە جوق.