Using OSS Hosting

Overview

What is OSS hosting

The OSS hosting solution allows you to store document processing results in your own OSS Bucket instead of service-side storage. It is suitable for scenarios with data privacy, compliance, and access control requirements:

Results stay on your side: Parse/Extract results are written directly to your OSS space, making it easy to perform subsequent business processing and access control.
Fine-grained access control: You can authorize the source file directory and result directory separately to achieve least privilege.
No secondary transfer costs: You no longer need to download results from the service side and transfer them yourself.

Integration method description (important)

Dimension	Current solution (parse-x API)
Authentication	Role trust is not supported. You must pass OSS STS temporary credentials (or a RAM user AK) with each request
Passed fields	`bucket` / `endpoint` / `access_key_id` / `access_key_secret` / `security_token` in `output.oss_config`
Result writing	The service writes to OSS directly using the STS credentials you pass in

Therefore, when using the current parse-x API for OSS hosting, you must obtain a set of STS temporary credentials (or a RAM user AK) that can access the target OSS Bucket, and pass them with every submit/query request.

Prerequisites

Create a RAM user (or RAM role)

If using a long-term AccessKey: create a RAM user and generate an AccessKey ID / AccessKey Secret for it (leave security_token empty).
If using STS temporary credentials (recommended): create a RAM role, then call the AssumeRole API to obtain temporary credentials (including security_token).

Create a least-privilege authorization policy

Under "Permissions → Policies → Create Policy", use the script editor to configure the following least-privilege policy (example policy name testParseXAccessOss):

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject"
      ],
      "Resource": "acs:oss:*:*:[your-bucket-name]/[your-source-directory]/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "oss:PutObject",
        "oss:GetObject"
      ],
      "Resource": "acs:oss:*:*:[your-bucket-name]/[your-result-directory]/*"
    }
  ]
}

Field descriptions:

Permission	Purpose	Description
`oss:GetObject` (source directory)	Read source files	Required when source files use your OSS signed URLs (`file_url` pointing to your OSS objects)
`oss:PutObject` (result directory)	Write parse results	Required when the service writes results to the specified directory in your OSS
`oss:GetObject` (result directory)	Read results	Required when the query API returns result URLs / generates signed URLs

Replace [your-bucket-name], [your-source-directory], and [your-result-directory] with your actual bucket and directories. For simplicity, you can also relax Resource to acs:oss:*:*:[your-bucket-name]/*, but for security reasons we recommend keeping directory-level least-privilege authorization.

Attach the policy to the RAM user / role

After creating the policy, go to "Permissions → Add Permissions" for the corresponding RAM user (or role) and select the policy you just created (set the resource scope to "Account Level") to complete authorization.

Obtain STS temporary credentials (recommended)

Call the STS AssumeRole API with the ARN of the RAM role above to obtain temporary credentials:

Request: sts.aliyuncs.com  -  Action: AssumeRole
         RoleArn        : acs:ram::{account-id}:role/{role-name}
         RoleSessionName: parse-x-oss-access
Response: AccessKeyId / AccessKeySecret / SecurityToken / Expiration

Fill the three returned fields into access_key_id, access_key_secret, and security_token in your requests.

If using a RAM user's long-term AK, only fill in access_key_id and access_key_secret; security_token can be omitted.

STS temporary credentials have a validity period (Expiration). Make sure the credentials have not expired during calls; obtain new ones after they expire.

Usage

API endpoints and authentication

Environment	Address
Staging	`https://{workspace}.cn-beijing.pre-maas.aliyuncs.com/api/v2/apps/pre-parse-x/{endpoint}`
Production	`https://{workspace}.cn-beijing.maas.aliyuncs.com/api/v2/apps/parse-x/{endpoint}`

Submit & query parse tasks `/parse/submit`, `/parse/result`

Before calling, make sure you have obtained an API Key. For details, see Submit Parse Task and Query Parse Task. Field descriptions (output.oss_config):

Field	Type	Required	Description
`bucket`	string	Yes	Your OSS Bucket name
`endpoint`	string	Yes	OSS Endpoint, e.g. `oss-cn-hangzhou.aliyuncs.com`
`access_key_id`	string	Yes	STS temporary credential or RAM user AK ID
`access_key_secret`	string	Yes	Corresponding secret
`security_token`	string	No	SecurityToken of the STS temporary credential; omit when using a long-term AK

Extract tasks `/extract/submit` and `/extract/result`

Before calling, make sure you have obtained an API Key. For details, see Submit Extract Task and Query Extract Task. Field descriptions (output.oss_config):

Field	Type	Required	Description
`bucket`	string	Yes	Your OSS Bucket name
`endpoint`	string	Yes	OSS Endpoint, e.g. `oss-cn-hangzhou.aliyuncs.com`
`access_key_id`	string	Yes	STS temporary credential or RAM user AK ID
`access_key_secret`	string	Yes	Corresponding secret
`security_token`	string	No	SecurityToken of the STS temporary credential; omit when using a long-term AK

OSS-side configuration requirements and troubleshooting

The following are common scenarios where "your OSS configuration" causes "the service to fail when calling with your STS credentials". When troubleshooting, refer to the actual error message and check each item one by one.

Insufficient permissions (AccessDenied / HTTP 403)

Symptom: Returns FileDownloadFailed (download failed) or CustomerOssWriteFailed (failed to write to your OSS), or OSS reports AccessDenied. Cause: The RAM user/role that the STS credentials belong to is not authorized for oss:GetObject (source directory) or oss:PutObject (result directory), or the Resource path configuration does not match the actual directory. Resolution: Check the authorization policy against section 2.2, and confirm that Action and Resource (including the trailing /*) cover the actual read/write paths.

Block Public Access

Related documentation: Block Public Access Symptom: The service is denied (403 Forbidden) when accessing your bucket with STS credentials, even though the credentials themselves are valid. Cause: You have enabled "Block Public Access" at the bucket or account level, which blocks access requests from the public internet/untrusted conditions and may also affect authorized access. Resolution:

If you must keep "Block Public Access" enabled, confirm that the parsing service's access source is allowed, or use an internal Endpoint in the same region (e.g. oss-cn-hangzhou-internal.aliyuncs.com, which must be in the same region as the access source).
If not required, temporarily disable the feature to verify whether it is the root cause of the blocking.

Hotlink protection (Referer validation)

Related documentation: Hotlink Protection Symptom: The service is denied (403) when reading/writing your bucket via SDK (without a Referer header). Cause: You have enabled OSS hotlink protection with a Referer whitelist / checked "Do not allow empty Referer". Service-side SDK requests usually do not carry a Referer header and are rejected as invalid sources. Resolution:

Allow empty Referer in the hotlink protection configuration (check allow), or add the service-side request source to the whitelist.
If hotlink protection must be enabled, confirm that service-side SDK requests will not be blocked by Referer validation.

Related documentation: Cross-Origin Resource Sharing Symptom: Result URLs cannot be accessed directly from the browser (the browser reports a CORS cross-origin error); service-side read/write itself is not affected by CORS. Cause: CORS only constrains browser-side cross-origin requests. If your frontend accesses result URLs directly (without a server-side proxy) and the bucket has no CORS rules configured, the browser will block the request. Resolution: If you need direct browser-side access to results, configure CORS rules under OSS "Data Security → Cross-Origin Settings" (allowed origins, GET/PUT methods, and response headers to expose).

Bucket Policy / authorization policy

Symptom: STS credentials are valid, but access is still denied (403). Cause: A Bucket Policy (authorization policy) configured on your bucket explicitly Denys access from the service or STS principal, or restricts the access source. Resolution: Check the bucket's "Permissions → Authorization Policy" and confirm there is no Deny statement blocking service access.

Expired STS credentials / Endpoint mismatch

Symptom: Authentication failure or 403 is returned. Cause:

The STS temporary credentials have passed their Expiration, or the security_token does not match the access_key_id.
The endpoint does not match the bucket's actual region (e.g. the bucket is in cn-shanghai but the endpoint is set to oss-cn-hangzhou.aliyuncs.com).

Resolution: Obtain new, unexpired STS credentials; confirm that the endpoint matches the bucket's region.

Troubleshooting checklist

No.	Check item	Resolution
1	Whether RAM/bucket permissions cover `GetObject` / `PutObject`	Check the policy's Action and Resource paths
2	Whether "Block Public Access" is enabled	Allow the source or use an internal Endpoint / temporarily disable to verify
3	Whether "hotlink protection" is enabled and empty Referer is not allowed	Allow empty Referer or add the source to the whitelist
4	Whether direct browser-side access to results is needed	Configure CORS rules
5	Whether the Bucket Policy contains Deny statements	Remove or adjust the Deny
6	Whether STS credentials have expired / token matches AK	Obtain new credentials
7	Whether the endpoint matches the bucket region	Correct the endpoint

Error code reference

Enum constant	HTTP	Business code	Description	English message
`OSS_NOSUCKKEY_ERROR`	400	32001	Target file could not be matched in OSS	Target file that could not be matched in OSS.
`OSS_INVALIDACCESSKEYID_ERROR`	400	32002	The provided OSS Access Key Id does not exist	The OSS Access Key Id you provided does not exist in our records.
`OSS_SIGNATUREDOESNOTMATCH_ERROR`	400	32003	Request signature verification mismatch	The request signature we calculated does not match the signature you provided. Check your key and signing method.
`OSS_INVALIDSECURITYTOKEN_ERROR`	400	32004	The provided security token is invalid	The security token you provided is invalid.
`OSS_ACCESSDENIED_ERROR`	400	32005	No permission to access this object due to bucket ACL	You have no right to access this object because of bucket acl.
`OSS_CHECK_ERROR`	400	32006	OSS check failed	oss check fail.
`OSS_NoSuchBucket_ERROR`	400	32007	The specified bucket does not exist	The specified bucket does not exist.
`OSS_AccessForbidden_ERROR`	400	32008	Access forbidden	AccessForbidden

Notes and best practices

Credential security: STS temporary credentials have a validity period. Do not hardcode long-term AKs; we recommend dynamically obtaining credentials via STS AssumeRole and limiting the validity period to the shortest time needed for the task.
Least privilege: Only grant GetObject on the source directory and PutObject + GetObject on the result directory; avoid full-bucket authorization.
Endpoint selection: The actual endpoint provided by the service prevails:

Public Endpoint (oss-cn-hangzhou.aliyuncs.com) is universal, but traffic goes over the public internet.
Internal Endpoint (oss-cn-hangzhou-internal.aliyuncs.com) must be in the same region as the access source and guarantees traffic "stays off the public internet".

Result directory: The specific prefix where results are written is determined by the service side; make sure the result directory Resource in your policy covers that prefix.
Source file privacy: If source files also need to "stay off the public internet", pass your own OSS signed URL as file_url (with an expiration) to avoid permanently exposing source files.

​Overview

​What is OSS hosting

​Integration method description (important)

​Prerequisites

​Create a RAM user (or RAM role)

​Create a least-privilege authorization policy

​Attach the policy to the RAM user / role

​Obtain STS temporary credentials (recommended)

​Usage

​API endpoints and authentication

​Submit & query parse tasks /parse/submit, /parse/result

​Extract tasks /extract/submit and /extract/result

​OSS-side configuration requirements and troubleshooting

​Insufficient permissions (AccessDenied / HTTP 403)

​Block Public Access

​Hotlink protection (Referer validation)

​Cross-Origin Resource Sharing (CORS)

​Bucket Policy / authorization policy

​Expired STS credentials / Endpoint mismatch

​Troubleshooting checklist

​Error code reference

​Notes and best practices