Namespace: microsoft.graph
You can use createLink action to share a DriveItem via a sharing link.
The createLink action will create a new sharing link if the specified link type doesn't already exist for the calling application.
If a sharing link of the specified type already exists for the app, the existing sharing link will be returned.
DriveItem resources inherit sharing permissions from their ancestors.
This API is available in the following national cloud deployments.
| Global service |
US Government L4 |
US Government L5 (DOD) |
China operated by 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type |
Least privileged permissions |
Higher privileged permissions |
| Delegated (work or school account) |
Files.ReadWrite |
Files.ReadWrite.All, Sites.ReadWrite.All |
| Delegated (personal Microsoft account) |
Files.ReadWrite |
Files.ReadWrite.All |
| Application |
Files.ReadWrite.All |
Sites.ReadWrite.All |
HTTP request
POST /drives/{driveId}/items/{itemId}/createLink
POST /groups/{groupId}/drive/items/{itemId}/createLink
POST /me/drive/items/{itemId}/createLink
POST /sites/{siteId}/drive/items/{itemId}/createLink
POST /users/{userId}/drive/items/{itemId}/createLink
Request body
The body of the request defines properties of the sharing link your application is requesting.
The request should be a JSON object with the following properties.
| Name |
Type |
Description |
| type |
string |
The type of sharing link to create. Either view, edit, or embed. |
| password |
string |
The password of the sharing link that is set by the creator. Optional and OneDrive Personal only. |
| expirationDateTime |
string |
A String with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission. |
| retainInheritedPermissions |
Boolean |
Optional. If true (default), any existing inherited permissions are retained on the shared item when sharing this item for the first time. If false, all existing permissions are removed when sharing for the first time. |
| scope |
string |
Optional. The scope of link to create. Either anonymous, organization, or users. |
Link types
The following values are allowed for the type parameter.
| Type value |
Description |
view |
Creates a read-only link to the DriveItem. |
edit |
Creates a read-write link to the DriveItem. |
embed |
Creates an embeddable link to the DriveItem. This option is only available for files in OneDrive personal. |
Scope types
The following values are allowed for the scope parameter.
If the scope parameter is not specified, the default link type for the organization is created.
| Value |
Description |
anonymous |
Anyone with the link has access, without needing to sign in. This may include people outside of your organization. Anonymous link support may be disabled by an administrator. |
organization |
Anyone signed into your organization (tenant) can use the link to get access. Only available in OneDrive for Business and SharePoint. |
users |
Share only with people you choose inside or outside the organization. |
Response
If successful, this method returns a single Permission resource in the response body that represents the requested sharing permissions.
The response will be 201 Created if a new sharing link is created for the item or 200 OK if an existing link is returned.
Example
The following example requests a sharing link to be created for the DriveItem specified by {itemId} in the user's OneDrive.
The sharing link is configured to be read-only and usable by anyone with the link.
All existing permissions are removed when sharing for the first time if retainInheritedPermissions is false.
Request
POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-type: application/json
{
"type": "view",
"password": "ThisIsMyPrivatePassword",
"scope": "anonymous",
"retainInheritedPermissions": false
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.CreateLink;
var requestBody = new CreateLinkPostRequestBody
{
Type = "view",
Password = "ThisIsMyPrivatePassword",
Scope = "anonymous",
RetainInheritedPermissions = false,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].CreateLink.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
mgc drives items create-link post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"type": "view",\
"password": "ThisIsMyPrivatePassword",\
"scope": "anonymous",\
"retainInheritedPermissions": false\
}\
'
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
requestBody := graphdrives.NewCreateLinkPostRequestBody()
type := "view"
requestBody.SetType(&type)
password := "ThisIsMyPrivatePassword"
requestBody.SetPassword(&password)
scope := "anonymous"
requestBody.SetScope(&scope)
retainInheritedPermissions := false
requestBody.SetRetainInheritedPermissions(&retainInheritedPermissions)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createLink, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").CreateLink().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.createlink.CreateLinkPostRequestBody createLinkPostRequestBody = new com.microsoft.graph.drives.item.items.item.createlink.CreateLinkPostRequestBody();
createLinkPostRequestBody.setType("view");
createLinkPostRequestBody.setPassword("ThisIsMyPrivatePassword");
createLinkPostRequestBody.setScope("anonymous");
createLinkPostRequestBody.setRetainInheritedPermissions(false);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").createLink().post(createLinkPostRequestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
type: 'view',
password: 'ThisIsMyPrivatePassword',
scope: 'anonymous',
retainInheritedPermissions: false
};
await client.api('/me/drive/items/{item-id}/createLink')
.post(permission);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\CreateLink\CreateLinkPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateLinkPostRequestBody();
$requestBody->setType('view');
$requestBody->setPassword('ThisIsMyPrivatePassword');
$requestBody->setScope('anonymous');
$requestBody->setRetainInheritedPermissions(false);
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->createLink()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Files
$params = @{
type = "view"
password = "ThisIsMyPrivatePassword"
scope = "anonymous"
retainInheritedPermissions = $false
}
New-MgDriveItemLink -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.create_link.create_link_post_request_body import CreateLinkPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateLinkPostRequestBody(
type = "view",
password = "ThisIsMyPrivatePassword",
scope = "anonymous",
retain_inherited_permissions = False,
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').create_link.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "123ABC",
"roles": ["write"],
"link": {
"type": "view",
"scope": "anonymous",
"webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
"application": {
"id": "1234",
"displayName": "Sample Application"
},
},
"hasPassword": true
}
Creating company sharable links
OneDrive for Business and SharePoint support company sharable links.
These are similar to anonymous links, except they only work for members of the owning organization.
To create a company sharable link, use the scope parameter with a value of organization.
Request
POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-Type: application/json
{
"type": "edit",
"scope": "organization"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.CreateLink;
var requestBody = new CreateLinkPostRequestBody
{
Type = "edit",
Scope = "organization",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].CreateLink.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
mgc drives items create-link post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
"type": "edit",\
"scope": "organization"\
}\
'
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
requestBody := graphdrives.NewCreateLinkPostRequestBody()
type := "edit"
requestBody.SetType(&type)
scope := "organization"
requestBody.SetScope(&scope)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createLink, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").CreateLink().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.createlink.CreateLinkPostRequestBody createLinkPostRequestBody = new com.microsoft.graph.drives.item.items.item.createlink.CreateLinkPostRequestBody();
createLinkPostRequestBody.setType("edit");
createLinkPostRequestBody.setScope("organization");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").createLink().post(createLinkPostRequestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
type: 'edit',
scope: 'organization'
};
await client.api('/me/drive/items/{item-id}/createLink')
.post(permission);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\CreateLink\CreateLinkPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateLinkPostRequestBody();
$requestBody->setType('edit');
$requestBody->setScope('organization');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->createLink()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Files
$params = @{
type = "edit"
scope = "organization"
}
New-MgDriveItemLink -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.create_link.create_link_post_request_body import CreateLinkPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateLinkPostRequestBody(
type = "edit",
scope = "organization",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').create_link.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "123ABC",
"roles": ["write"],
"link": {
"type": "edit",
"scope": "organization",
"webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
"application": {
"id": "1234",
"displayName": "Sample Application"
},
},
}
Creating embeddable links
When using the embed link type, the webUrl returned can be embedded in an <iframe> HTML element.
When an embed link is created the webHtml property contains the HTML code for an <iframe> to host the content.
Note: Embed links are only supported for OneDrive personal.
Request
POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-Type: application/json
{
"type": "embed"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Drives.Item.Items.Item.CreateLink;
var requestBody = new CreateLinkPostRequestBody
{
Type = "embed",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].CreateLink.PostAsync(requestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
//other-imports
)
requestBody := graphdrives.NewCreateLinkPostRequestBody()
type := "embed"
requestBody.SetType(&type)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createLink, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").CreateLink().Post(context.Background(), requestBody, nil)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.drives.item.items.item.createlink.CreateLinkPostRequestBody createLinkPostRequestBody = new com.microsoft.graph.drives.item.items.item.createlink.CreateLinkPostRequestBody();
createLinkPostRequestBody.setType("embed");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").createLink().post(createLinkPostRequestBody);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
type: 'embed'
};
await client.api('/me/drive/items/{item-id}/createLink')
.post(permission);
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\CreateLink\CreateLinkPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateLinkPostRequestBody();
$requestBody->setType('embed');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->createLink()->post($requestBody)->wait();
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Import-Module Microsoft.Graph.Files
$params = @{
type = "embed"
}
New-MgDriveItemLink -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.create_link.create_link_post_request_body import CreateLinkPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateLinkPostRequestBody(
type = "embed",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').create_link.post(request_body)
For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "123ABC",
"roles": ["read"],
"link": {
"type": "embed",
"webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
"webUrl": "https://onedrive.live.com/...",
"application": {
"id": "1234",
"displayName": "Sample Application"
},
}
}
- Links created using this action do not expire unless a default expiration policy is enforced for the organization.
- Links are visible in the sharing permissions for the item and can be removed by an owner of the item.
- Links always point to the current version of a item unless the item is checked out (SharePoint only).